@airoom/nextmin-node 1.4.5 → 2.0.1

package/dist/utils/Events.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Events = exports.events = void 0;
+exports.getModelEvent = getModelEvent;
+const events_1 = require("events");
+const Logger_1 = __importDefault(require("./Logger"));
+/**
+ * NextMinEvents is a central event emitter for the NextMin ecosystem.
+ * It allows components to hook into CRUD and system events.
+ */
+class NextMinEvents extends events_1.EventEmitter {
+    constructor() {
+        super();
+        // Increase max listeners to avoid warnings in complex apps
+        this.setMaxListeners(100);
+    }
+    /**
+     * Typed emit to provide better DX (Developer Experience)
+     */
+    emitEvent(event, payload) {
+        Logger_1.default.info('NextMinEvents', `Emitting event: ${event}`);
+        this.emit(event, payload);
+    }
+}
+// Singleton instance
+exports.events = new NextMinEvents();
+// Standard event constants
+exports.Events = {
+    // Document events
+    BEFORE_CREATE: 'before:doc:create',
+    AFTER_CREATE: 'after:doc:create',
+    BEFORE_UPDATE: 'before:doc:update',
+    AFTER_UPDATE: 'after:doc:update',
+    BEFORE_DELETE: 'before:doc:delete',
+    AFTER_DELETE: 'after:doc:delete',
+    BEFORE_READ: 'before:doc:read',
+    AFTER_READ: 'after:doc:read',
+    // Auth events
+    AUTH_LOGIN: 'auth:login',
+    AUTH_LOGOUT: 'auth:logout',
+    AUTH_SIGNUP: 'auth:signup',
+    // System events
+    SCHEMA_UPDATE: 'schema:update',
+    SERVER_START: 'server:start',
+    SERVER_STOP: 'server:stop',
+};
+/**
+ * Helper to generate model-specific event names
+ */
+function getModelEvent(modelName, action, phase = 'after') {
+    return `${modelName.toLowerCase()}:${phase}:${action}`;
+}

package/dist/utils/Logger.js

@@ -9,8 +9,7 @@ const util_1 = require("util");
 const path_1 = __importDefault(require("path"));
 class Logger {
     constructor() {
-        const env = process.env.NODE_ENV || 'development';
-        this.isDevelopment = env === 'development';
+        this.isDevelopment = process.env.APP_MODE !== 'production' && process.env.NODE_ENV !== 'production';
     }
     getCallerInfo() {
         const originalPrepareStackTrace = Error.prepareStackTrace;
@@ -24,12 +23,11 @@ class Logger {
             !frame.getFileName()?.includes('Logger.ts') &&
             !frame.getFunctionName()?.includes('getCallerInfo'));
         if (!callerFrame) {
-            return 'unknown:0:0';
+            return 'unknown:0';
         }
-        const fileName = path_1.default.relative(process.cwd(), callerFrame.getFileName() || 'unknown');
+        const fileName = path_1.default.basename(callerFrame.getFileName() || 'unknown');
         const lineNumber = callerFrame.getLineNumber() || 0;
-        const columnNumber = callerFrame.getColumnNumber() || 0;
-        return `${fileName}:${lineNumber}:${columnNumber}`;
+        return `${fileName}:${lineNumber}`;
     }
     formatMessage(level, label, messages) {
         const callerInfo = this.getCallerInfo();
@@ -66,12 +64,16 @@ class Logger {
         }
     }
     warn(label, ...messages) {
-        const formatted = this.formatMessage('WARN', label, messages);
-        console.warn(formatted);
+        if (this.isDevelopment) {
+            const formatted = this.formatMessage('WARN', label, messages);
+            console.warn(formatted);
+        }
     }
     error(label, ...messages) {
-        const formatted = this.formatMessage('ERROR', label, messages);
-        console.error(formatted);
+        if (this.isDevelopment) {
+            const formatted = this.formatMessage('ERROR', label, messages);
+            console.error(formatted);
+        }
     }
 }
 exports.Logger = Logger;

package/dist/utils/QueryCache.d.ts

@@ -0,0 +1,16 @@
+export interface CacheConfig {
+    ttl?: number;
+    enabled?: boolean;
+}
+export declare class QueryCache {
+    private cache;
+    private enabled;
+    private defaultTtl;
+    constructor(config?: CacheConfig);
+    generateKey(collection: string, operation: string, args: any): Promise<string>;
+    private sortObjectKeys;
+    get<T>(key: string): Promise<T | null>;
+    set(key: string, value: any, ttl?: number): Promise<void>;
+    invalidateCollection(collection: string): Promise<void>;
+    private getCollectionVersion;
+}

package/dist/utils/QueryCache.js

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryCache = void 0;
+const keyv_1 = __importDefault(require("keyv"));
+const redis_1 = __importDefault(require("@keyv/redis"));
+const Logger_1 = __importDefault(require("./Logger"));
+class QueryCache {
+    constructor(config = {}) {
+        this.enabled = config.enabled !== false; // Enabled by default
+        this.defaultTtl = config.ttl || 60000; // 60 seconds default
+        const redisUrl = process.env.REDIS_URL;
+        if (redisUrl) {
+            try {
+                const store = new redis_1.default(redisUrl);
+                this.cache = new keyv_1.default({ store });
+                Logger_1.default.info('QueryCache', `Initialized with Redis store at ${redisUrl}`);
+            }
+            catch (err) {
+                Logger_1.default.error('QueryCache', 'Failed to initialize Redis store, falling back to basic map', err);
+                this.cache = new keyv_1.default();
+            }
+        }
+        else {
+            // Falls back to in-memory map
+            this.cache = new keyv_1.default();
+            Logger_1.default.info('QueryCache', 'Initialized with in-memory store (no REDIS_URL provided)');
+        }
+        this.cache.on('error', (err) => Logger_1.default.warn('QueryCache', 'Connection Error', err));
+    }
+    async generateKey(collection, operation, args) {
+        try {
+            const version = await this.getCollectionVersion(collection);
+            const sortedArgs = this.sortObjectKeys(args);
+            const strArgs = JSON.stringify(sortedArgs);
+            return `nm:cache:${collection}:v${version}:${operation}:${strArgs}`;
+        }
+        catch (e) {
+            // Fallback if JSON.stringify fails (e.g. circular refs, though unlikely in simple queries)
+            const v = await this.getCollectionVersion(collection);
+            return `nm:cache:${collection}:v${v}:${operation}:${Date.now()}`;
+        }
+    }
+    sortObjectKeys(obj) {
+        if (obj === null || typeof obj !== 'object') {
+            return obj;
+        }
+        if (Array.isArray(obj)) {
+            return obj.map(item => this.sortObjectKeys(item));
+        }
+        const sortedObj = {};
+        Object.keys(obj).sort().forEach(key => {
+            sortedObj[key] = this.sortObjectKeys(obj[key]);
+        });
+        return sortedObj;
+    }
+    async get(key) {
+        if (!this.enabled)
+            return null;
+        try {
+            const data = await this.cache.get(key);
+            if (data) {
+                // Return a deep clone to prevent external mutation of cached objects
+                return JSON.parse(JSON.stringify(data));
+            }
+            return null;
+        }
+        catch (err) {
+            Logger_1.default.warn('QueryCache', `Failed to get key ${key}`, err);
+            return null;
+        }
+    }
+    async set(key, value, ttl) {
+        if (!this.enabled || value === undefined)
+            return;
+        try {
+            // Store a clean copy
+            const cleanValue = JSON.parse(JSON.stringify(value));
+            await this.cache.set(key, cleanValue, ttl || this.defaultTtl);
+        }
+        catch (err) {
+            Logger_1.default.warn('QueryCache', `Failed to set key ${key}`, err);
+        }
+    }
+    async invalidateCollection(collection) {
+        if (!this.enabled)
+            return;
+        try {
+            // Increment collection version:
+            const vKey = `nm:collection:version:${collection}`;
+            let currentVersion = await this.cache.get(vKey) || 0;
+            await this.cache.set(vKey, currentVersion + 1, 0); // never expire the version
+            Logger_1.default.info('QueryCache', `Invalidated cache for collection: ${collection} (version bumped)`);
+        }
+        catch (err) {
+            Logger_1.default.warn('QueryCache', `Failed to invalidate collection ${collection}`, err);
+        }
+    }
+    async getCollectionVersion(collection) {
+        const vKey = `nm:collection:version:${collection}`;
+        return (await this.cache.get(vKey)) || 0;
+    }
+}
+exports.QueryCache = QueryCache;

package/dist/utils/SchemaLoader.d.ts

@@ -6,6 +6,11 @@ type PublicSchema = Omit<Schema, 'attributes'> & {
     showCount: boolean;
     attributes: PublicAttributes;
     allowedMethods: Schema['allowedMethods'];
+    extends?: string;
+    group?: string;
+    schemaType?: string;
+    columnsSelector?: string[];
+    actions?: Schema['actions'];
 };
 export declare class SchemaLoader {
     private emitter;
@@ -33,9 +38,9 @@ export declare class SchemaLoader {
         [key: string]: Schema;
     };
     /** CLIENT/API: sanitized map with private attributes removed */
-    getPublicSchemas(): Record<string, PublicSchema>;
+    getPublicSchemas(showPrivate?: boolean): Record<string, PublicSchema>;
     /** CLIENT/API convenience: array of { modelName, attributes, allowedMethods } */
-    getPublicSchemaList(): Array<PublicSchema>;
+    getPublicSchemaList(showPrivate?: boolean): Array<PublicSchema>;
     /** Strip any attr marked private; also remove the `private` flag from others */
     /** Keep private/sensitive flags so the UI and policy layer can decide.
      *  We only shallow-clone values to avoid leaking references.

package/dist/utils/SchemaLoader.js

@@ -138,13 +138,14 @@ class SchemaLoader {
                             continue;
                         if (Object.prototype.hasOwnProperty.call(mergedAttrs, key)) {
                             const val = mergedAttrs[key];
+                            const isInherited = !Object.prototype.hasOwnProperty.call(schema.attributes, key);
                             if (Array.isArray(val) && val[0] && typeof val[0] === 'object') {
                                 const { unique: _u, index: _i, ...rest } = val[0];
-                                mergedAttrs[key] = [{ ...rest }];
+                                mergedAttrs[key] = [{ ...rest, inherited: isInherited }];
                             }
                             else if (val && typeof val === 'object') {
                                 const { unique: _u, index: _i, ...rest } = val;
-                                mergedAttrs[key] = { ...rest };
+                                mergedAttrs[key] = { ...rest, inherited: isInherited };
                             }
                         }
                     }
@@ -153,14 +154,50 @@ class SchemaLoader {
                         ...baseSchema.allowedMethods,
                         ...schema.allowedMethods,
                     };
+                    // Merge access (policies/masks/reachability)
+                    if (baseSchema.access) {
+                        const baseAccess = baseSchema.access;
+                        if (!schema.access)
+                            schema.access = {};
+                        // 1. Selective Merge for bypassPrivacy (combine roles)
+                        if (baseAccess.bypassPrivacy?.roles) {
+                            if (!schema.access.bypassPrivacy)
+                                schema.access.bypassPrivacy = {};
+                            const baseRoles = baseAccess.bypassPrivacy.roles;
+                            const currentRoles = schema.access.bypassPrivacy.roles || [];
+                            schema.access.bypassPrivacy.roles = Array.from(new Set([...baseRoles, ...currentRoles]));
+                        }
+                        // 2. Inherit masks/filters/restrictions ONLY if not defined in child
+                        // Note: We DO NOT inherit public/authenticated/roles reachability here.
+                        // Child schemas should manage their own reachability.
+                        if (!schema.access.readMask)
+                            schema.access.readMask = baseAccess.readMask;
+                        if (!schema.access.writeDeny)
+                            schema.access.writeDeny = baseAccess.writeDeny;
+                        if (!schema.access.queryFilter)
+                            schema.access.queryFilter = baseAccess.queryFilter;
+                        if (!schema.access.createDefaults)
+                            schema.access.createDefaults = baseAccess.createDefaults;
+                        if (!schema.access.restrictions)
+                            schema.access.restrictions = baseAccess.restrictions;
+                        if (!schema.access.conditions)
+                            schema.access.conditions = baseAccess.conditions;
+                    }
                     // Inject hidden link field to base (used for storage join)
                     // Ensure hidden link field
                     const linkField = 'baseId';
                     if (!schema.attributes[linkField]) {
+                        const isUserExt = baseName.toLowerCase() === 'users';
                         schema.attributes[linkField] = {
                             type: 'ObjectId',
                             ref: baseName,
-                            private: true,
+                            private: !isUserExt,
+                            required: false,
+                            label: isUserExt ? 'Associate User Account (Optional)' : 'Base Record',
+                            show: isUserExt ? 'username' : 'id',
+                            index: true,
+                            unique: isUserExt,
+                            sparse: isUserExt,
                         };
                     }
                 }
@@ -288,13 +325,13 @@ class SchemaLoader {
         return this.schemas;
     }
     /** CLIENT/API: sanitized map with private attributes removed */
-    getPublicSchemas() {
+    getPublicSchemas(showPrivate = false) {
         const out = {};
         for (const [name, s] of Object.entries(this.schemas)) {
             // if (this.nonOverridableSchemas.has(name)) continue;
             // Clone sanitized attributes and add timestamps
             const attributesWithTimestamps = {
-                ...this.sanitizeAttributes(s.attributes),
+                ...this.sanitizeAttributes(s.attributes, showPrivate),
                 createdAt: { type: 'datetime' },
                 updatedAt: { type: 'datetime' },
             };
@@ -303,20 +340,25 @@ class SchemaLoader {
                 showCount: s.showCount,
                 allowedMethods: s.allowedMethods,
                 attributes: attributesWithTimestamps,
+                extends: s.extends,
+                group: s.group,
+                schemaType: s.schemaType,
+                columnsSelector: s.columnsSelector,
+                actions: s.actions,
             };
         }
         return out;
     }
     /** CLIENT/API convenience: array of { modelName, attributes, allowedMethods } */
-    getPublicSchemaList() {
-        const pub = this.getPublicSchemas();
+    getPublicSchemaList(showPrivate = false) {
+        const pub = this.getPublicSchemas(showPrivate);
         return Object.values(pub);
     }
     /** Strip any attr marked private; also remove the `private` flag from others */
     /** Keep private/sensitive flags so the UI and policy layer can decide.
      *  We only shallow-clone values to avoid leaking references.
      */
-    sanitizeAttributes(attrs) {
+    sanitizeAttributes(attrs, showPrivate = false) {
         const out = {};
         if (!attrs || typeof attrs !== 'object' || Array.isArray(attrs))
             return out;
@@ -325,13 +367,12 @@ class SchemaLoader {
             if (Array.isArray(attr)) {
                 const elem = attr[0];
                 if (elem && typeof elem === 'object') {
-                    // If the inner descriptor is private, omit this field entirely from public schema
-                    if (elem.private) {
+                    // If the inner descriptor is private and we're not showing private, omit this field entirely
+                    if (elem.private && !showPrivate) {
                         continue;
                     }
-                    // Keep as an array with a single shallow-cloned descriptor (without leaking private flag)
-                    const { private: _omit, ...rest } = elem;
-                    out[key] = [{ ...rest }];
+                    // Preserve the descriptor, including the 'private' flag if showPrivate is true
+                    out[key] = [{ ...elem }];
                 }
                 else {
                     // Fallback: keep as-is (no private flag to check)
@@ -341,13 +382,12 @@ class SchemaLoader {
             }
             // Single attribute object
             if (attr && typeof attr === 'object') {
-                // If marked private, omit from public schema entirely
-                if (attr.private) {
+                // If marked private and we're not showing private, omit from public schema entirely
+                if (attr.private && !showPrivate) {
                     continue;
                 }
-                // Shallow clone and drop the private flag if present
-                const { private: _omit, ...rest } = attr;
-                out[key] = { ...rest };
+                // Preserve the descriptor, including the 'private' flag if showPrivate is true
+                out[key] = { ...attr };
                 continue;
             }
             // Unexpected primitives — pass through

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@airoom/nextmin-node",
-  "version": "1.4.5",
+  "version": "2.0.1",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "rm -rf dist && tsc --project tsconfig.json && copyfiles -u 2 \"src/schemas/**/*\" dist/schemas",
     "watch": "tsc --project tsconfig.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "prepublishOnly": "npm run build && npm pack --dry-run | (! grep -E '\\bsrc/|\\.map$')"
   },
   "dependencies": {
@@ -17,19 +20,31 @@
     "chokidar": "^4.0.3",
     "fast-glob": "^3.3.1",
     "jsonwebtoken": "^9.0.2",
+    "keyv": "^5.2.3",
     "kleur": "^4.1.5",
-    "mongoose": "^8.17.0",
+    "@keyv/redis": "^4.0.1",
+    "mongodb": "^6.21.0",
+    "mongoose": "^8.18.0",
     "mongoose-autopopulate": "^1.1.0",
+    "mssql": "^12.2.0",
     "multer": "^2.0.2",
-    "socket.io": "^4.7.5"
+    "mysql2": "^3.16.1",
+    "pg": "^8.17.2",
+    "reflect-metadata": "^0.2.2",
+    "socket.io": "^4.7.5",
+    "sqlite3": "^5.1.7",
+    "typeorm": "^0.3.28"
   },
   "devDependencies": {
     "@types/bcrypt": "^6.0.0",
     "@types/chokidar": "^2.1.7",
     "@types/jsonwebtoken": "^9.0.10",
     "@types/multer": "^2.0.0",
+    "@vitest/coverage-v8": "^4.0.17",
     "copyfiles": "^2.4.1",
-    "typescript": "^5.3.3"
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.17"
   },
   "files": [
     "dist",

package/dist/database/InMemoryAdapter.d.ts

@@ -1,15 +0,0 @@
-import { DatabaseAdapter, FieldIndexSpec } from './DatabaseAdapter';
-import { ReadOptions, Schema } from '../models/BaseModel';
-export declare class InMemoryAdapter implements DatabaseAdapter {
-    private data;
-    connect(): Promise<void>;
-    disconnect(): Promise<void>;
-    registerSchemas(schemas: Record<string, Schema>): void;
-    create(collection: string, data: any, schemaDefinition: Schema): Promise<any>;
-    read(collection: string, query: any, limit?: number, skip?: number, schemaDefinition?: Schema, _includePrivateFields?: boolean, _options?: ReadOptions): Promise<any[]>;
-    update(collection: string, id: string, data: any, schemaDefinition: Schema): Promise<any>;
-    delete(collection: string, id: string, schemaDefinition: Schema): Promise<any>;
-    count(collection: string, query: any, schemaDefinition: Schema): Promise<number>;
-    syncIndexes(_modelName: string, _desired: FieldIndexSpec): Promise<void>;
-    private generateId;
-}

package/dist/database/InMemoryAdapter.js

@@ -1,71 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.InMemoryAdapter = void 0;
-class InMemoryAdapter {
-    constructor() {
-        this.data = {};
-    }
-    async connect() {
-        // No-op for in-memory
-    }
-    async disconnect() {
-        // No-op for in-memory
-    }
-    registerSchemas(schemas) {
-        // No-op for in-memory, but you could validate schemas here if needed
-    }
-    async create(collection, data, schemaDefinition) {
-        if (!this.data[collection]) {
-            this.data[collection] = [];
-        }
-        // Generate a simple id if not present
-        if (!data.id) {
-            data.id = `${Date.now()}_${Math.random()}`;
-        }
-        this.data[collection].push(data);
-        return data;
-    }
-    async read(collection, query, limit, skip, schemaDefinition, _includePrivateFields, _options) {
-        const allData = this.data[collection] || [];
-        let results = allData.filter((item) => {
-            return Object.entries(query).every(([key, value]) => item[key] === value);
-        });
-        if (limit !== undefined && skip !== undefined) {
-            results = results.slice(skip, skip + limit);
-        }
-        return results;
-    }
-    async update(collection, id, data, schemaDefinition) {
-        const allData = this.data[collection] || [];
-        const index = allData.findIndex((item) => item.id === id);
-        if (index === -1) {
-            throw new Error(`Document with id ${id} not found in collection '${collection}'`);
-        }
-        this.data[collection][index] = { ...allData[index], ...data };
-        return this.data[collection][index];
-    }
-    async delete(collection, id, schemaDefinition) {
-        const allData = this.data[collection] || [];
-        const index = allData.findIndex((item) => item.id === id);
-        if (index === -1) {
-            throw new Error(`Document with id ${id} not found in collection '${collection}'`);
-        }
-        const deleted = this.data[collection].splice(index, 1)[0];
-        return deleted;
-    }
-    async count(collection, query, schemaDefinition) {
-        const allData = this.data[collection] || [];
-        // Count documents matching the query
-        const results = allData.filter((item) => {
-            return Object.entries(query).every(([key, value]) => item[key] === value);
-        });
-        return results.length;
-    }
-    async syncIndexes(_modelName, _desired) {
-        // no-op for memory adapter
-    }
-    generateId() {
-        return Math.random().toString(36).substr(2, 9);
-    }
-}
-exports.InMemoryAdapter = InMemoryAdapter;

package/dist/database/MongoAdapter.d.ts

@@ -1,52 +0,0 @@
-import { DatabaseAdapter, FieldIndexSpec } from './DatabaseAdapter';
-import { ReadOptions, Schema as NextMinSchema } from '../models/BaseModel';
-export declare class MongoAdapter implements DatabaseAdapter {
-    private url;
-    private dbName;
-    private connection;
-    /** Map keyed by lowercased modelName (e.g., "users", "roles") → Mongoose Model */
-    private models;
-    constructor(url: string, dbName: string);
-    connect(): Promise<void>;
-    disconnect(): Promise<void>;
-    /**
-     * Register (and re-register) all schemas.
-     * - Drops compiled models that no longer exist.
-     * - Recompiles every current model so validators reflect latest schema.
-     */
-    registerSchemas(schemas: Record<string, NextMinSchema>): Promise<void>;
-    /** Optional hook used by the router when schemas are removed. */
-    unregisterSchemas(names: string[]): Promise<void>;
-    /** Optional single-model drop hook. */
-    dropModel(nameRaw: string): Promise<void>;
-    /**
-     * Delete a compiled model by case-insensitive match.
-     * Works whether we compiled it as "Users" or "users".
-     */
-    private safeDeleteModel;
-    private safeDropCollection;
-    /** Build a fresh Mongoose schema from our NextMin schema definition. */
-    private buildMongooseSchema;
-    private mapAttribute;
-    private mapScalar;
-    /**
-     * Resolve (or lazily create) the compiled model for a schema.
-     * Uses schema.modelName as the Mongoose model name and
-     * (schema.collection ?? modelName).toLowerCase() as the collection.
-     */
-    private getModel;
-    private getSchema;
-    private convertQueryFieldsToObjectId;
-    private toAppObject;
-    create(collection: string, data: any, schemaDefinition: NextMinSchema, includePrivateFields?: boolean): Promise<any>;
-    read(collection: string, query: any, limit: number | undefined, skip: number | undefined, schemaDefinition: NextMinSchema, includePrivateFields?: boolean, options?: ReadOptions): Promise<any[]>;
-    count(collection: string, query: any, schemaDefinition: NextMinSchema): Promise<number>;
-    update(collection: string, id: string, data: any, schemaDefinition: NextMinSchema, includePrivateFields?: boolean): Promise<any>;
-    delete(collection: string, id: string, schemaDefinition: NextMinSchema, includePrivateFields?: boolean): Promise<any>;
-    private getNativeCollectionByModelName;
-    /** Create/drop single-field indexes based on schema plan.
-     *  Only touches indexes named with the prefix below (won't touch user indexes).
-     */
-    private managedIndexName;
-    syncIndexes(modelName: string, spec: FieldIndexSpec): Promise<void>;
-}