@rapidd/core 2.1.0

package/src/core/i18n.ts

@@ -0,0 +1,144 @@
+import { readdirSync } from 'fs';
+import path from 'path';
+
+const ROOT = process.env.ROOT || '';
+const DEFAULT_STRINGS_PATH = ROOT ? path.join(ROOT, 'locales') : './locale';
+
+/**
+ * Singleton LanguageDict class for efficient translation management.
+ * All dictionaries are loaded once at initialization and cached in memory.
+ */
+export class LanguageDict {
+    private static _dictionaries: Record<string, Record<string, string>> = {};
+    private static _available: string[] = [];
+    private static _dictionaryPath: string | null = null;
+    private static _defaultLanguage: string = 'en_US';
+    private static _initialized: boolean = false;
+
+    /**
+     * Initialize the LanguageDict system
+     */
+    static initialize(dictionaryPath: string = DEFAULT_STRINGS_PATH, defaultLanguage: string = 'en_US'): void {
+        if (this._initialized && this._dictionaryPath === dictionaryPath) {
+            return;
+        }
+
+        this._dictionaryPath = dictionaryPath;
+        this._defaultLanguage = defaultLanguage;
+        this._dictionaries = {};
+        this._available = [];
+
+        try {
+            const files = readdirSync(dictionaryPath);
+
+            for (const fileName of files) {
+                if (path.extname(fileName) === '.json') {
+                    const langCode = path.parse(fileName).name;
+                    try {
+                        const dictPath = path.join(dictionaryPath, fileName);
+                        // eslint-disable-next-line @typescript-eslint/no-require-imports
+                        this._dictionaries[langCode] = require(dictPath);
+                        this._available.push(langCode);
+                    } catch (error) {
+                        console.error(`Failed to load dictionary for ${langCode}:`, (error as Error).message);
+                    }
+                }
+            }
+
+            this._initialized = true;
+        } catch (error) {
+            console.error('Failed to initialize LanguageDict:', (error as Error).message);
+            this._dictionaries = {};
+            this._available = [];
+        }
+    }
+
+    /**
+     * Get a translated string with optional parameter interpolation
+     */
+    static get(key: string, data: Record<string, unknown> | null = null, language: string | null = null): string {
+        if (!this._initialized) {
+            this.initialize();
+        }
+
+        const lang = language || this._defaultLanguage;
+        const dictionary = this._dictionaries[lang] || this._dictionaries[this._defaultLanguage] || {};
+
+        let translated: string | undefined = dictionary[key];
+
+        if (translated === undefined) {
+            return key;
+        }
+
+        // Handle nested translations ({{key}} syntax)
+        translated = translated.replace(/{{\w+}}/g, (match: string) => {
+            const nestedKey = match.slice(2, -2);
+            return this.get(nestedKey, data, lang);
+        });
+
+        // Handle parameter interpolation ({key} syntax)
+        if (data !== null && typeof data === 'object') {
+            translated = translated.replace(/\{(\w+)\}/g, (match: string, paramKey: string) => {
+                return data[paramKey] !== undefined ? String(data[paramKey]) : match;
+            });
+        }
+
+        return translated;
+    }
+
+    /**
+     * Get all available language codes
+     */
+    static getAvailableLanguages(): string[] {
+        if (!this._initialized) {
+            this.initialize();
+        }
+        return [...this._available];
+    }
+
+    /**
+     * Get the entire dictionary for a specific language
+     */
+    static getDictionary(language: string): Record<string, string> {
+        if (!this._initialized) {
+            this.initialize();
+        }
+        return this._dictionaries[language] || this._dictionaries[this._defaultLanguage] || {};
+    }
+
+    /**
+     * Check if a language is available
+     */
+    static hasLanguage(language: string): boolean {
+        if (!this._initialized) {
+            this.initialize();
+        }
+        return this._available.includes(language);
+    }
+
+    /**
+     * Reload dictionaries from disk
+     */
+    static reload(): void {
+        this._initialized = false;
+        this.initialize(this._dictionaryPath || DEFAULT_STRINGS_PATH, this._defaultLanguage);
+    }
+
+    // Instance-based API for backward compatibility
+    private language: string;
+
+    constructor(language: string) {
+        if (!LanguageDict._initialized) {
+            LanguageDict.initialize();
+        }
+        this.language = language;
+    }
+
+    get(key: string, data: Record<string, unknown> | null = null): string {
+        return LanguageDict.get(key, data, this.language);
+    }
+
+    getDictionary(): Record<string, string> {
+        return LanguageDict.getDictionary(this.language);
+    }
+}

package/src/core/middleware.ts

@@ -0,0 +1,123 @@
+import type { MiddlewareHook, MiddlewareOperation, MiddlewareContext, MiddlewareFn } from '../types';
+
+const middlewareRegistry = new Map<string, MiddlewareFn[]>();
+
+const OPERATIONS: MiddlewareOperation[] = ['create', 'update', 'upsert', 'upsertMany', 'delete', 'get', 'getMany', 'count'];
+const HOOKS: MiddlewareHook[] = ['before', 'after'];
+
+function getKey(hook: string, operation: string, model: string = '*'): string {
+    return `${hook}:${operation}:${model}`;
+}
+
+/**
+ * Register a middleware function
+ */
+function use(hook: MiddlewareHook, operation: MiddlewareOperation, fn: MiddlewareFn, model: string = '*'): void {
+    if (!HOOKS.includes(hook)) {
+        throw new Error(`Invalid hook '${hook}'. Must be one of: ${HOOKS.join(', ')}`);
+    }
+    if (!OPERATIONS.includes(operation)) {
+        throw new Error(`Invalid operation '${operation}'. Must be one of: ${OPERATIONS.join(', ')}`);
+    }
+    if (typeof fn !== 'function') {
+        throw new Error('Middleware must be a function');
+    }
+
+    const key = getKey(hook, operation, model);
+    if (!middlewareRegistry.has(key)) {
+        middlewareRegistry.set(key, []);
+    }
+    middlewareRegistry.get(key)!.push(fn);
+}
+
+/**
+ * Remove a specific middleware function
+ */
+function remove(hook: MiddlewareHook, operation: MiddlewareOperation, fn: MiddlewareFn, model: string = '*'): boolean {
+    const key = getKey(hook, operation, model);
+    const middlewares = middlewareRegistry.get(key);
+    if (!middlewares) return false;
+
+    const index = middlewares.indexOf(fn);
+    if (index > -1) {
+        middlewares.splice(index, 1);
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Clear all middleware for a specific hook/operation/model combination
+ */
+function clear(hook?: MiddlewareHook, operation?: MiddlewareOperation, model?: string): void {
+    if (!hook && !operation && !model) {
+        middlewareRegistry.clear();
+        return;
+    }
+    const key = getKey(hook!, operation!, model);
+    middlewareRegistry.delete(key);
+}
+
+/**
+ * Get all middleware functions for a specific hook/operation/model.
+ * Returns both model-specific and global ('*') middleware.
+ */
+function getMiddleware(hook: MiddlewareHook, operation: MiddlewareOperation, model: string): MiddlewareFn[] {
+    const globalKey = getKey(hook, operation, '*');
+    const modelKey = getKey(hook, operation, model);
+
+    const globalMiddleware = middlewareRegistry.get(globalKey) || [];
+    const modelSpecific = middlewareRegistry.get(modelKey) || [];
+
+    return [...globalMiddleware, ...modelSpecific];
+}
+
+/**
+ * Execute middleware chain for a given context
+ */
+async function execute(hook: MiddlewareHook, operation: MiddlewareOperation, context: MiddlewareContext): Promise<MiddlewareContext> {
+    const middlewares = getMiddleware(hook, operation, context.model.name);
+
+    let ctx: MiddlewareContext = { ...context };
+    for (const fn of middlewares) {
+        const result = await fn(ctx);
+        if (result !== undefined) {
+            ctx = result;
+        }
+        if (ctx.abort) break;
+    }
+
+    return ctx;
+}
+
+/**
+ * Create a middleware context object
+ */
+function createContext(
+    model: { name: string },
+    operation: string,
+    params: Record<string, unknown>,
+    user: MiddlewareContext['user'] = null
+): MiddlewareContext {
+    return {
+        model,
+        operation,
+        user,
+        timestamp: new Date(),
+        ...params,
+        abort: false,
+        skip: false,
+        softDelete: false,
+    } as MiddlewareContext;
+}
+
+export const modelMiddleware = {
+    use,
+    remove,
+    clear,
+    getMiddleware,
+    execute,
+    createContext,
+    OPERATIONS,
+    HOOKS,
+};

package/src/core/prisma.ts

@@ -0,0 +1,236 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import path from 'path';
+import type { RLSVariables, DatabaseProvider, AdapterResult, AclConfig } from '../types';
+import * as dmmf from './dmmf';
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { PrismaClient, Prisma } = require(path.join(process.cwd(), 'prisma', 'client'));
+
+/** Request context storage for RLS variables across async operations */
+export const requestContext = new AsyncLocalStorage<{ variables: RLSVariables }>();
+
+/** Validates that an RLS identifier contains only safe characters (letters, digits, underscores) */
+const IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function validateIdentifier(value: string, name: string): string {
+    if (!IDENTIFIER_RE.test(value)) {
+        throw new Error(`[RLS] Invalid identifier for ${name}: "${value}". Only letters, numbers, and underscores allowed.`);
+    }
+    return value;
+}
+
+/** RLS namespace for SQL session variable prefix */
+const RLS_NAMESPACE = validateIdentifier(process.env.RLS_NAMESPACE || 'app', 'RLS_NAMESPACE');
+
+// =====================================================
+// DATABASE ADAPTER FACTORY
+// =====================================================
+
+function detectProvider(connectionString: string): DatabaseProvider {
+    if (!connectionString) return 'postgresql';
+    if (connectionString.startsWith('mysql://') || connectionString.startsWith('mariadb://')) {
+        return 'mysql';
+    }
+    return 'postgresql';
+}
+
+function parseMySQLConnectionString(connectionString: string): Record<string, unknown> {
+    const url = new URL(connectionString);
+    return {
+        host: url.hostname,
+        port: parseInt(url.port, 10) || 3306,
+        user: url.username,
+        password: url.password,
+        database: url.pathname.slice(1),
+        connectionLimit: 10,
+    };
+}
+
+export function createAdapter(connectionString: string, provider: string | null = null): AdapterResult {
+    const detectedProvider = (provider || process.env.DATABASE_PROVIDER || detectProvider(connectionString)) as DatabaseProvider;
+
+    if (detectedProvider === 'mysql' || (detectedProvider as string) === 'mariadb') {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { PrismaMariaDb } = require('@prisma/adapter-mariadb');
+        const config = parseMySQLConnectionString(connectionString);
+        const adapter = new PrismaMariaDb(config);
+        return { adapter, pool: null, provider: 'mysql' };
+    } else {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { PrismaPg } = require('@prisma/adapter-pg');
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { Pool } = require('pg');
+        const pool = new Pool({ connectionString });
+        const adapter = new PrismaPg(pool);
+        return { adapter, pool, provider: 'postgresql' };
+    }
+}
+
+// =====================================================
+// BASE PRISMA CLIENTS
+// =====================================================
+
+const authConnection = createAdapter(process.env.DATABASE_URL_ADMIN || process.env.DATABASE_URL || '');
+const baseConnection = createAdapter(process.env.DATABASE_URL || '');
+
+export const dbProvider: DatabaseProvider = baseConnection.provider;
+
+/** Whether RLS is enabled. Auto: true for PostgreSQL, false for MySQL. Override with RLS_ENABLED env var. */
+export const rlsEnabled: boolean = process.env.RLS_ENABLED !== undefined
+    ? process.env.RLS_ENABLED === 'true'
+    : dbProvider === 'postgresql';
+
+export const authPrisma = new PrismaClient({
+    adapter: authConnection.adapter,
+    log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
+});
+
+const basePrisma = new PrismaClient({
+    adapter: baseConnection.adapter,
+    log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
+});
+
+// =====================================================
+// RLS HELPER FUNCTIONS
+// =====================================================
+
+function sanitizeRLSValue(value: string | number | null | undefined): string {
+    if (value === null || value === undefined) return '';
+    return String(value).replace(/'/g, "''");
+}
+
+export async function setRLSVariables(tx: any, variables: RLSVariables): Promise<void> {
+    for (const [name, value] of Object.entries(variables)) {
+        if (value === null || value === undefined) continue;
+        const safeName = validateIdentifier(name, name);
+        const safeValue = sanitizeRLSValue(value);
+
+        if (dbProvider === 'mysql') {
+            await tx.$executeRawUnsafe(`SET @${RLS_NAMESPACE}_${safeName} = '${safeValue}'`);
+        } else {
+            await tx.$executeRawUnsafe(`SET LOCAL ${RLS_NAMESPACE}.${safeName} = '${safeValue}'`);
+        }
+    }
+}
+
+export async function resetRLSVariables(tx: any, variables: RLSVariables): Promise<void> {
+    try {
+        for (const name of Object.keys(variables)) {
+            const safeName = validateIdentifier(name, name);
+            if (dbProvider === 'mysql') {
+                await tx.$executeRawUnsafe(`SET @${RLS_NAMESPACE}_${safeName} = NULL`);
+            } else {
+                await tx.$executeRawUnsafe(`RESET ${RLS_NAMESPACE}.${safeName}`);
+            }
+        }
+    } catch {
+        // Ignore errors on reset
+    }
+}
+
+// =====================================================
+// EXTENDED PRISMA WITH AUTOMATIC RLS
+// =====================================================
+
+export const prisma = basePrisma.$extends({
+    query: {
+        async $allOperations({ operation, args, query, model }: any) {
+            if (!rlsEnabled) return query(args);
+
+            const context = requestContext.getStore();
+            const variables = context?.variables;
+
+            if (!variables || Object.keys(variables).length === 0) {
+                return query(args);
+            }
+
+            if (operation === '$transaction') {
+                return basePrisma.$transaction(async (tx: any) => {
+                    await setRLSVariables(tx, variables);
+                    return query(args);
+                });
+            }
+
+            return basePrisma.$transaction(async (tx: any) => {
+                await setRLSVariables(tx, variables);
+
+                if (model) {
+                    return tx[model][operation](args);
+                } else {
+                    return tx[operation](args);
+                }
+            });
+        },
+    },
+});
+
+// =====================================================
+// TRANSACTION HELPERS
+// =====================================================
+
+export async function prismaTransaction(
+    callback: ((tx: any) => Promise<any>) | Array<(tx: any) => Promise<any>>,
+    options?: { timeout?: number }
+): Promise<any> {
+    const context = requestContext.getStore();
+
+    return basePrisma.$transaction(async (tx: any) => {
+        const variables = context?.variables;
+        if (rlsEnabled && variables && Object.keys(variables).length > 0) {
+            await setRLSVariables(tx, variables);
+        }
+
+        if (Array.isArray(callback)) {
+            return await Promise.all(callback.map((fn: (tx: any) => Promise<any>) => fn(tx)));
+        }
+        return await callback(tx);
+    }, options);
+}
+
+// =====================================================
+// GRACEFUL SHUTDOWN
+// =====================================================
+
+export async function disconnectAll(): Promise<void> {
+    await authPrisma.$disconnect();
+    await basePrisma.$disconnect();
+    if (authConnection.pool && typeof (authConnection.pool as any).end === 'function') {
+        await (authConnection.pool as any).end();
+    }
+    if (baseConnection.pool && typeof (baseConnection.pool as any).end === 'function') {
+        await (baseConnection.pool as any).end();
+    }
+}
+
+process.on('beforeExit', async () => {
+    await disconnectAll();
+});
+
+// =====================================================
+// INITIALIZATION
+// =====================================================
+
+export async function initializeDMMF(): Promise<any> {
+    return dmmf.loadDMMF();
+}
+
+// Auto-initialize DMMF on module load
+initializeDMMF();
+
+// =====================================================
+// LAZY ACL & MIDDLEWARE
+// =====================================================
+
+let _acl: AclConfig | null = null;
+export function getAcl(): AclConfig {
+    if (!_acl) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            _acl = require('../config/acl').default || require('../config/acl');
+        } catch {
+            _acl = { model: {} };
+        }
+    }
+    return _acl!;
+}
+
+export { PrismaClient, Prisma, dmmf };

package/src/index.ts

@@ -0,0 +1,112 @@
+/**
+ * Rapidd Framework - Main exports
+ *
+ * @example
+ * import { Model, QueryBuilder, prisma, Auth, ErrorResponse } from 'rapidd';
+ *
+ * class Users extends Model {
+ *     constructor(options) {
+ *         super('users', options);
+ *     }
+ * }
+ */
+
+// ── ORM ──────────────────────────────────────────────────────────────────────
+export { Model } from './orm/Model';
+export { QueryBuilder } from './orm/QueryBuilder';
+
+// ── Database ─────────────────────────────────────────────────────────────────
+export {
+    prisma,
+    authPrisma,
+    prismaTransaction,
+    getAcl,
+    setRLSVariables,
+    resetRLSVariables,
+    requestContext,
+    dbProvider,
+    rlsEnabled
+} from './core/prisma';
+
+export * as dmmf from './core/dmmf';
+
+// ── Authentication ───────────────────────────────────────────────────────────
+export { Auth } from './auth/Auth';
+export { SessionStoreManager, createStore } from './auth/stores';
+export type { ISessionStore } from './auth/stores/ISessionStore';
+
+// ── Errors & Responses ───────────────────────────────────────────────────────
+export { ErrorResponse, Response } from './core/errors';
+
+// ── Middleware ───────────────────────────────────────────────────────────────
+export { modelMiddleware } from './core/middleware';
+
+// ── Utilities ────────────────────────────────────────────────────────────────
+export { ApiClient, ApiClientError } from './utils/ApiClient';
+export { Mailer } from './utils/Mailer';
+export { env } from './utils';
+
+// ── Environment ──────────────────────────────────────────────────────────────
+export {
+    validateEnv,
+    getEnv,
+    getAllEnv,
+    isProduction,
+    isDevelopment,
+    isTest
+} from './core/env';
+
+// ── Plugins ──────────────────────────────────────────────────────────────────
+export { uploadPlugin } from './plugins/upload';
+export { default as responsePlugin } from './plugins/response';
+export { default as apiPlugin } from './plugins/response'; // backward compat alias
+export { default as authPlugin } from './plugins/auth';
+export { default as languagePlugin } from './plugins/language';
+export { default as securityPlugin } from './plugins/security';
+export { default as rateLimitPlugin, RateLimiter } from './plugins/rateLimit';
+export { default as rateLimiterPlugin } from './plugins/rateLimit'; // backward compat alias
+export { default as rlsPlugin } from './plugins/rls';
+
+// ── App Builder ──────────────────────────────────────────────────────────────
+export { buildApp } from './app';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+export type {
+    RapiddUser,
+    AuthStrategy,
+    RouteAuthConfig,
+    ModelOptions,
+    GetManyResult,
+    UpsertManyResult,
+    UpsertManyOptions,
+    ModelAcl,
+    AclConfig,
+    MiddlewareContext,
+    MiddlewareHook,
+    MiddlewareOperation,
+    RLSVariables,
+    RlsContextFn
+} from './types';
+
+export type {
+    ServiceConfig,
+    EndpointConfig,
+    AuthConfig,
+    RequestOptions,
+    ApiResponse
+} from './utils/ApiClient';
+
+export type {
+    EmailConfig,
+    EmailOptions,
+    EmailAttachment,
+    EmailResult
+} from './utils/Mailer';
+
+export type {
+    UploadOptions,
+    AllowedType,
+    UploadedFile
+} from './plugins/upload';
+
+export type { EnvConfig } from './core/env';

package/src/middleware/model.ts

@@ -0,0 +1,61 @@
+/**
+ * Model Middleware — Register before/after hooks for CRUD operations.
+ *
+ * Import this file in main.ts (before start()) to activate middleware.
+ * Hooks run for all models by default; pass a model name as the last
+ * argument to scope a hook to a specific model.
+ *
+ * Usage:
+ *   import './src/middleware/model';
+ *
+ * Available hooks:  'before' | 'after'
+ * Available ops:    'create' | 'update' | 'upsert' | 'upsertMany'
+ *                   | 'delete' | 'get' | 'getMany' | 'count'
+ */
+
+import { modelMiddleware } from '../core/middleware';
+
+// ── Timestamps (all models) ─────────────────────────
+// Automatically set createdAt on create
+
+// modelMiddleware.use('before', 'create', async (ctx) => {
+//     ctx.data = { ...ctx.data, createdAt: new Date(), createdBy: ctx.user?.id };
+//     return ctx;
+// });
+
+// Automatically set updatedAt on update
+
+// modelMiddleware.use('before', 'update', async (ctx) => {
+//     ctx.data = { ...ctx.data, updatedAt: new Date(), updatedBy: ctx.user?.id };
+//     return ctx;
+// });
+
+// ── Soft Delete (specific model) ────────────────────
+// Convert delete to an update that sets deletedAt
+
+// modelMiddleware.use('before', 'delete', async (ctx) => {
+//     ctx.softDelete = true;
+//     ctx.data = { deletedAt: new Date(), deletedBy: ctx.user?.id };
+//     return ctx;
+// }, 'posts');
+
+// ── Transform Response ──────────────────────────────
+// Add computed fields after fetching
+
+// modelMiddleware.use('after', 'get', async (ctx) => {
+//     const result = ctx.result as Record<string, unknown> | undefined;
+//     if (result?.firstName && result?.lastName) {
+//         result.fullName = `${result.firstName} ${result.lastName}`;
+//     }
+//     return ctx;
+// }, 'users');
+
+// ── Abort on Condition ──────────────────────────────
+// Prevent creation if a condition is not met
+
+// modelMiddleware.use('before', 'create', async (ctx) => {
+//     if (!ctx.data?.email) {
+//         ctx.abort = true; // stops the operation
+//     }
+//     return ctx;
+// }, 'users');