@rapidd/core 2.1.1 → 2.1.3

package/.env.example

@@ -68,3 +68,9 @@ RLS_ENABLED=
 # Namespace prefix for SQL session variables (default: app)
 RLS_NAMESPACE=app
 # Configure RLS variables in src/config/rls.ts
+
+# ── Logging ───────────────────────────────────────────
+# essential (default), fine, or finest
+LOG_LEVEL=essential
+# Directory for log files (default: logs/). Empty string disables file logging.
+LOG_DIR=logs

package/README.md

@@ -31,18 +31,14 @@ Rapidd generates a fully-featured REST API from your database schema — then ge
 
 ```bash
 mkdir my-api && cd my-api
-npx rapidd create-project # scaffold project files
-npm install
+npx @rapidd/core create-project && npm install
 ```
 
-```env
-DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
-```
+Set `DATABASE_URL` in `.env`, then add your schema in `prisma/schema.prisma`(or create from DB via `npx prisma db pull`):
 
 ```bash
-npx prisma db pull        # introspect existing database
-npx rapidd build          # generate models, routes & ACL scaffold
-npm run dev               # http://localhost:3000
+npx rapidd build            # generate models, routes & ACL scaffold
+npm run dev                 # http://localhost:3000
 ```
 
 Every table gets full CRUD endpoints. Auth is enabled automatically when a user table is detected. Every auto-detected value — auth fields, password hashing, JWT secrets, session store — is overridable via env vars. See [`.env.example`](.env.example) for the full list.
@@ -51,25 +47,22 @@ Every table gets full CRUD endpoints. Auth is enabled automatically when a user
 
 ---
 
-## Features
-
-| Feature | PostgreSQL | MySQL/MariaDB |
-|---------|:----------:|:-------------:|
-| CRUD API generation | ✓ | ✓ |
-| Query filtering (20+ operators) | ✓ | ✓ |
-| Relations & deep includes | ✓ | ✓ |
-| Field selection | ✓ | ✓ |
-| JWT authentication (4 methods) | ✓ | ✓ |
-| Per-model ACL | ✓ | ✓ |
-| Row-Level Security (database-enforced) | ✓ | — |
-| Rate limiting (Redis + memory fallback) | ✓ | ✓ |
-| File uploads with MIME validation | ✓ | ✓ |
-| SMTP mailer with EJS templates | ✓ | ✓ |
-| Config-driven HTTP client | ✓ | ✓ |
-| i18n (10 languages) | ✓ | ✓ |
-| Security headers (HSTS, CSP, etc.) | ✓ | ✓ |
-
-> **MySQL note:** ACL provides application-level access control for all databases. RLS adds database-enforced row filtering as a second layer (PostgreSQL-only). For MySQL, ACL is your primary access control mechanism and covers most use cases. See the **[Access Control wiki](https://github.com/MertDalbudak/rapidd/wiki/Access-Control-(ACL))** for details.
+## How It Compares
+
+| | Rapidd | Hasura | PostgREST | Supabase | Strapi |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Full source code ownership | ✓ | — | — | — | ✓ |
+| Schema-first (no UI) | ✓ | ✓ | ✓ | ✓ | — |
+| REST API | ✓ | — | ✓ | ✓ | ✓ |
+| Multi-database | ✓ | ✓ | — | — | ✓ |
+| Built-in auth | ✓ | — | — | ✓ | ✓ |
+| Per-model ACL | ✓ | ✓ | — | — | ✓ |
+| Row-level security | ✓* | ✓ | ✓ | ✓ | — |
+| Before/after middleware | ✓ | — | — | — | ✓ |
+| Custom routes alongside generated | ✓ | — | — | ✓ | ✓ |
+| No vendor dependency | ✓ | ✓ | ✓ | — | ✓ |
+
+<sub>* PostgreSQL only. All other features support PostgreSQL and MySQL/MariaDB.</sub>
 
 ---
 
@@ -235,11 +228,9 @@ docker build -t my-api . && docker run -p 3000:3000 --env-file .env my-api
 | [`@rapidd/core`](https://www.npmjs.com/package/@rapidd/core) | Framework runtime, project scaffolding, and unified `npx rapidd` CLI |
 | [`@rapidd/build`](https://www.npmjs.com/package/@rapidd/build) | Code generation — models, routes, and ACL from your Prisma schema |
 
-All commands go through `npx rapidd`:
-
 ```bash
-npx rapidd create-project   # scaffold a new project (@rapidd/core)
-npx rapidd build             # generate from schema  (@rapidd/build)
+npx @rapidd/core create-project   # scaffold a new project
+npx rapidd build                   # generate from schema (after npm install)
 ```
 
 ---

package/bin/cli.js

@@ -87,6 +87,19 @@ function createProject() {
         }
     }
 
+    // Read versions from this package's own package.json so they never drift
+    const corePkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+    const coreDeps = corePkg.dependencies || {};
+    const coreDevDeps = corePkg.devDependencies || {};
+
+    function pick(source, keys) {
+        const result = {};
+        for (const key of keys) {
+            if (source[key]) result[key] = source[key];
+        }
+        return result;
+    }
+
     // Generate a fresh package.json for the new project
     const pkg = {
         name: projectName,
@@ -97,41 +110,19 @@ function createProject() {
             dev: 'tsx watch main.ts',
             build: 'tsc',
         },
-        engines: { node: '>=24.0.0' },
-        dependencies: {
-            '@fastify/cookie': '^11.0.2',
-            '@fastify/cors': '^11.0.0',
-            '@fastify/formbody': '^8.0.2',
-            '@fastify/multipart': '^9.4.0',
-            '@fastify/static': '^9.0.0',
-            '@prisma/adapter-mariadb': '^7.0.1',
-            '@prisma/adapter-pg': '^7.0.1',
-            '@prisma/client': '^7.0.1',
-            '@prisma/internals': '^7.0.1',
-            'bcrypt': '^6.0.0',
-            'dotenv': '^17.3.1',
-            'ejs': '^4.0.1',
-            'fastify': '^5.2.1',
-            'fastify-plugin': '^5.0.1',
-            'ioredis': '^5.6.1',
-            'jsonwebtoken': '^9.0.2',
-            'luxon': '^3.7.2',
-            'nodemailer': '^8.0.1',
-            'pg': '^8.16.3',
-        },
-        devDependencies: {
-            '@rapidd/build': '^2.1.3',
-            '@types/bcrypt': '^6.0.0',
-            '@types/ejs': '^3.1.5',
-            '@types/jsonwebtoken': '^9.0.8',
-            '@types/luxon': '^3.7.1',
-            '@types/node': '^22.12.0',
-            '@types/nodemailer': '^7.0.9',
-            '@types/pg': '^8.11.11',
-            'prisma': '^7.0.2',
-            'tsx': '^4.19.2',
-            'typescript': '^5.7.3',
-        },
+        engines: corePkg.engines || { node: '>=24.0.0' },
+        dependencies: pick(coreDeps, [
+            '@fastify/cookie', '@fastify/cors', '@fastify/formbody', '@fastify/multipart', '@fastify/static',
+            '@prisma/adapter-mariadb', '@prisma/adapter-pg', '@prisma/client', '@prisma/internals',
+            'bcrypt', 'dotenv', 'ejs', 'fastify', 'fastify-plugin',
+            'ioredis', 'jsonwebtoken', 'luxon', 'nodemailer', 'pg',
+        ]),
+        devDependencies: pick(coreDevDeps, [
+            '@rapidd/build',
+            '@types/bcrypt', '@types/ejs', '@types/jsonwebtoken', '@types/luxon',
+            '@types/node', '@types/nodemailer', '@types/pg',
+            'prisma', 'tsx', 'typescript',
+        ]),
     };
 
     fs.writeFileSync(

package/dockerfile

@@ -25,7 +25,7 @@ COPY prisma ./prisma
 RUN npx prisma generate --generator client
 
 # Stage 3: Runtime
-FROM node:24-alpine
+FROM node:current-alpine
 
 WORKDIR /app
 
@@ -50,8 +50,16 @@ COPY --chown=rapidd:nodejs public ./public
 
 RUN apk update && apk upgrade --no-cache && rm -rf /var/cache/apk/*
 
+RUN mkdir -p /app/uploads /app/temp/uploads /app/logs && \
+    chown -R rapidd:nodejs /app/uploads /app/temp /app/logs
+
+VOLUME ["/app/uploads", "/app/logs"]
+
 USER rapidd
 
 EXPOSE 3000
 
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD node -e "fetch('http://localhost:3000/').then(r => process.exit(r.status === 404 ? 0 : 1)).catch(() => process.exit(1))"
+
 ENTRYPOINT ["node", "dist/main.js"]

package/main.ts

@@ -1,6 +1,7 @@
 import 'dotenv/config';
 import { getEnv } from './src/core/env';
 import { buildApp } from './src/app';
+import { Logger } from './src/utils/Logger';
 
 /**
  * Application entry point
@@ -14,10 +15,15 @@ export async function start(): Promise<void> {
         const app = await buildApp();
 
         await app.listen({ port, host });
-        console.log(`[Rapidd] Server running at http://${host}:${port}`);
-        console.log(`[Rapidd] Environment: ${getEnv('NODE_ENV')}`);
+        Logger.log('Server running', { host, port });
+        Logger.log('Environment', { env: getEnv('NODE_ENV') });
+
+        // Warn if running compiled build with development NODE_ENV
+        if (process.argv[1]?.includes('/dist/') && getEnv('NODE_ENV') === 'development') {
+            Logger.warn('Running compiled build with NODE_ENV=development. Set NODE_ENV=production in your .env for production use.');
+        }
     } catch (err) {
-        console.error('[Startup Error]', (err as Error).message);
+        Logger.error(err as Error);
         process.exit(1);
     }
 }

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Code-first REST API framework for TypeScript. Database in, API out.",
   "main": "dist/main.js",
   "bin": {
@@ -83,7 +83,7 @@
     "pg": "^8.16.3"
   },
   "devDependencies": {
-    "@rapidd/build": "^2.1.3",
+    "@rapidd/build": "^2.1.5",
     "@types/bcrypt": "^6.0.0",
     "@types/ejs": "^3.1.5",
     "@types/jest": "^30.0.0",

package/src/app.ts

@@ -12,6 +12,7 @@ import { LanguageDict } from './core/i18n';
 import { disconnectAll } from './core/prisma';
 import { validateEnv } from './core/env';
 import { env } from './utils';
+import { Logger } from './utils/Logger';
 
 // Plugins
 import securityPlugin from './plugins/security';
@@ -22,6 +23,13 @@ import rlsPlugin from './plugins/rls';
 
 import type { RapiddOptions } from './types';
 
+// ─── BigInt Serialization ────────────────────────────
+// Prisma returns BigInt values that JSON.stringify cannot handle natively.
+// This polyfill converts them to strings during serialization.
+(BigInt.prototype as any).toJSON = function () {
+    return this.toString();
+};
+
 // ─── Path Setup ─────────────────────────────────────
 // Use process.cwd() as the project root — works from both source (tsx) and compiled (dist/) contexts.
 
@@ -176,7 +184,7 @@ async function loadRoutes(app: FastifyInstance, routePath: string): Promise<void
                         await app.register(plugin, { prefix: route });
                     }
                 } catch (err) {
-                    console.error(`Failed to load route ${route}:`, (err as Error).message);
+                    Logger.error(err as Error, { route });
                 }
             }
         }
@@ -186,12 +194,12 @@ async function loadRoutes(app: FastifyInstance, routePath: string): Promise<void
 
 // Handle uncaught errors
 process.on('uncaughtException', (err) => {
-    console.error('[Uncaught Exception]', err);
+    Logger.error(err);
     process.exit(1);
 });
 
-process.on('unhandledRejection', (reason, promise) => {
-    console.error('[Unhandled Rejection] at:', promise, 'reason:', reason);
+process.on('unhandledRejection', (reason) => {
+    Logger.error(reason as Error);
 });
 
 export default buildApp;

package/src/auth/Auth.ts

@@ -5,6 +5,7 @@ import { authPrisma } from '../core/prisma';
 import { ErrorResponse } from '../core/errors';
 import { createStore, SessionStoreManager } from './stores';
 import { loadDMMF, findUserModel, findIdentifierFields, findPasswordField } from '../core/dmmf';
+import { Logger } from '../utils/Logger';
 import type { RapiddUser, AuthOptions, AuthMethod, ISessionStore } from '../types';
 
 /**
@@ -99,7 +100,7 @@ export class Auth {
         try {
             await loadDMMF();
         } catch {
-            console.warn('[Auth] Could not load DMMF, auth auto-detection skipped');
+            Logger.warn('Auth: could not load DMMF, auto-detection skipped');
             return;
         }
 
@@ -109,7 +110,7 @@ export class Auth {
             // Check if a model name was explicitly configured
             if (!this.options.userModel) {
                 this._authDisabled = true;
-                console.log('[Auth] No user table detected in schema, auth disabled');
+                Logger.log('Auth: no user table detected, auth disabled');
                 return;
             }
             // Model name was set but not found in DMMF — warn but don't disable
@@ -142,7 +143,7 @@ export class Auth {
                 throw new Error('[Auth] JWT_SECRET is required in production. Generate one with: node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'hex\'))"');
             }
             this.options.jwt.secret = crypto.randomBytes(32).toString('hex');
-            console.warn('[Auth] No JWT_SECRET set, using auto-generated secret (sessions won\'t persist across restarts)');
+            Logger.warn('Auth: no JWT_SECRET set, using auto-generated secret (sessions won\'t persist across restarts)');
         }
         if (!this.options.jwt.refreshSecret) {
             if (process.env.NODE_ENV === 'production') {
@@ -173,7 +174,7 @@ export class Auth {
                 this._userModel = (authPrisma as any)[match];
                 return this._userModel;
             }
-            console.warn(`[Auth] userModel="${modelName}" not found in Prisma models`);
+            Logger.warn('Auth: userModel not found in Prisma models', { userModel: modelName });
         }
 
         for (const name of ['users', 'user', 'Users', 'User']) {

package/src/auth/stores/RedisStore.ts

@@ -1,5 +1,6 @@
 import Redis from 'ioredis';
 import { ISessionStore } from './ISessionStore';
+import { Logger } from '../../utils/Logger';
 
 /**
  * Redis session store using ioredis.
@@ -36,11 +37,11 @@ export class RedisStore extends ISessionStore {
             connectTimeout: 5000,
         });
 
-        this.client.on('connect', () => console.log('[RedisStore] Connected'));
-        this.client.on('ready', () => console.log('[RedisStore] Ready'));
-        this.client.on('error', (err: Error) => console.error('[RedisStore] Error:', err.message));
-        this.client.on('close', () => console.warn('[RedisStore] Connection closed'));
-        this.client.on('reconnecting', () => console.log('[RedisStore] Reconnecting...'));
+        this.client.on('connect', () => Logger.log('RedisStore connected'));
+        this.client.on('ready', () => Logger.log('RedisStore ready'));
+        this.client.on('error', (err: Error) => Logger.error(err));
+        this.client.on('close', () => Logger.warn('RedisStore connection closed'));
+        this.client.on('reconnecting', () => Logger.log('RedisStore reconnecting'));
 
         this._initialized = true;
         return this.client;

package/src/auth/stores/index.ts

@@ -1,6 +1,7 @@
 import { ISessionStore } from './ISessionStore';
 import { MemoryStore } from './MemoryStore';
 import { RedisStore } from './RedisStore';
+import { Logger } from '../../utils/Logger';
 
 const builtInStores: Record<string, new (options?: any) => ISessionStore> = {
     memory: MemoryStore,
@@ -41,7 +42,7 @@ export class SessionStoreManager extends ISessionStore {
 
         const StoreClass = builtInStores[this.storeName];
         if (!StoreClass) {
-            console.warn(`[SessionStore] Unknown store "${this.storeName}", using memory`);
+            Logger.warn('SessionStore: unknown store, using memory', { store: this.storeName });
             this._primaryStore = this._fallbackStore;
             this._initialized = true;
             return;
@@ -50,7 +51,7 @@ export class SessionStoreManager extends ISessionStore {
         try {
             this._primaryStore = new StoreClass({ ttl: this.ttl });
         } catch (err) {
-            console.warn(`[SessionStore] Failed to create ${this.storeName}: ${(err as Error).message}, using memory`);
+            Logger.warn('SessionStore: failed to create store, using memory', { store: this.storeName, error: (err as Error).message });
             this._primaryStore = this._fallbackStore;
         }
 
@@ -70,15 +71,15 @@ export class SessionStoreManager extends ISessionStore {
         try {
             const isHealthy = await this._primaryStore!.isHealthy();
             if (isHealthy && this._usingFallback) {
-                console.log(`[SessionStore] ${this.storeName} recovered, switching back from memory`);
+                Logger.log('SessionStore: recovered, switching back from memory', { store: this.storeName });
                 this._usingFallback = false;
             } else if (!isHealthy && !this._usingFallback) {
-                console.warn(`[SessionStore] ${this.storeName} unavailable, switching to memory`);
+                Logger.warn('SessionStore: unavailable, switching to memory', { store: this.storeName });
                 this._usingFallback = true;
             }
         } catch {
             if (!this._usingFallback) {
-                console.warn(`[SessionStore] ${this.storeName} health check failed, switching to memory`);
+                Logger.warn('SessionStore: health check failed, switching to memory', { store: this.storeName });
                 this._usingFallback = true;
             }
         }
@@ -98,7 +99,7 @@ export class SessionStoreManager extends ISessionStore {
         try {
             return await (this._primaryStore as any)[operation](...args);
         } catch (err) {
-            console.warn(`[SessionStore] ${this.storeName}.${operation} failed: ${(err as Error).message}, switching to memory`);
+            Logger.warn('SessionStore: operation failed, switching to memory', { store: this.storeName, operation, error: (err as Error).message });
             this._usingFallback = true;
             return (this._fallbackStore as any)[operation](...args);
         }

package/src/core/env.ts

@@ -51,6 +51,10 @@ export interface EnvConfig {
 
     // Proxy
     TRUST_PROXY?: boolean;
+
+    // Logging
+    LOG_LEVEL: 'essential' | 'fine' | 'finest';
+    LOG_DIR: string;
 }
 
 const REQUIRED_VARS = [
@@ -76,7 +80,9 @@ const DEFAULTS: Partial<Record<keyof EnvConfig, string | number | boolean>> = {
     REDIS_PORT: 6379,
     REDIS_DB_RATE_LIMIT: 0,
     REDIS_DB_AUTH: 1,
-    RLS_NAMESPACE: 'app'
+    RLS_NAMESPACE: 'app',
+    LOG_LEVEL: 'essential',
+    LOG_DIR: 'logs',
 };
 
 /**

package/src/core/i18n.ts

@@ -1,5 +1,6 @@
 import { readdirSync } from 'fs';
 import path from 'path';
+import { Logger } from '../utils/Logger';
 
 const ROOT = process.env.ROOT || '';
 const DEFAULT_STRINGS_PATH = ROOT ? path.join(ROOT, 'locales') : './locale';
@@ -40,14 +41,14 @@ export class LanguageDict {
                         this._dictionaries[langCode] = require(dictPath);
                         this._available.push(langCode);
                     } catch (error) {
-                        console.error(`Failed to load dictionary for ${langCode}:`, (error as Error).message);
+                        Logger.error(error as Error, { langCode });
                     }
                 }
             }
 
             this._initialized = true;
         } catch (error) {
-            console.error('Failed to initialize LanguageDict:', (error as Error).message);
+            Logger.error(error as Error);
             this._dictionaries = {};
             this._available = [];
         }

package/src/index.ts

@@ -44,6 +44,7 @@ export { modelMiddleware } from './core/middleware';
 // ── Utilities ────────────────────────────────────────────────────────────────
 export { ApiClient, ApiClientError } from './utils/ApiClient';
 export { Mailer } from './utils/Mailer';
+export { Logger } from './utils/Logger';
 export { env } from './utils';
 
 // ── Environment ──────────────────────────────────────────────────────────────
@@ -110,3 +111,4 @@ export type {
 } from './plugins/upload';
 
 export type { EnvConfig } from './core/env';
+export type { LogLevel } from './utils/Logger';

package/src/orm/Model.ts

@@ -177,6 +177,7 @@ class Model {
         const field = this.fields[fieldName];
         if (!field) return value;
         if (field.type === 'Int') return parseInt(value, 10);
+        if (field.type === 'BigInt') return BigInt(value);
         if (field.type === 'Float' || field.type === 'Decimal') return parseFloat(value);
         if (field.type === 'Boolean') return value === 'true';
         return value;
@@ -239,10 +240,13 @@ class Model {
         sortBy = sortBy?.trim();
         sortOrder = sortOrder?.trim();
 
-        // Validate sort field - fall back to default for composite PK names
+        // Validate sort field - fall back to default for composite PK names or missing 'id'
         if (!sortBy.includes('.') && this.fields[sortBy] == undefined) {
-            // If the sortBy is a composite key name (e.g., "email_companyId"), use first PK field
             if (sortBy === this.primaryKey && this.isCompositePK) {
+                // Composite key name (e.g., "email_companyId") → use first PK field
+                sortBy = this.defaultSortField;
+            } else if (sortBy === 'id') {
+                // Model doesn't have an 'id' field → fall back to actual primary key
                 sortBy = this.defaultSortField;
             } else {
                 throw new ErrorResponse(400, "invalid_sort_field", { sortBy, modelName: this.constructor.name });

package/src/orm/QueryBuilder.ts

@@ -1,5 +1,6 @@
 import { prisma, prismaTransaction, getAcl } from '../core/prisma';
 import { ErrorResponse } from '../core/errors';
+import { Logger } from '../utils/Logger';
 import * as dmmf from '../core/dmmf';
 import type {
     RelationConfig,
@@ -501,10 +502,10 @@ class QueryBuilder {
     /**
      * Parse numeric filter operators
      */
-    #filterNumber(value: string): Record<string, number> | null {
+    #filterNumber(value: string): Record<string, number | bigint> | null {
         const numOperators = ['lt:', 'lte:', 'gt:', 'gte:', 'eq:', 'ne:', 'between:'];
         const foundOperator = numOperators.find((op: string) => value.startsWith(op));
-        let numValue: string | number = value;
+        let numValue: string = value;
         let prismaOp = 'equals';
 
         if (foundOperator) {
@@ -517,19 +518,36 @@ class QueryBuilder {
                 case 'eq:': prismaOp = 'equals'; break;
                 case 'ne:': prismaOp = 'not'; break;
                 case 'between:': {
-                    // Support between for decimals: between:1.5;3.7
-                    const [start, end] = (numValue as string).split(';').map((v: string) => parseFloat(v.trim()));
-                    if (isNaN(start) || isNaN(end)) return null;
+                    const parts = numValue.split(';').map((v: string) => v.trim());
+                    const [startStr, endStr] = parts;
+                    const start = this.#parseNumericValue(startStr);
+                    const end = this.#parseNumericValue(endStr);
+                    if (start == null || end == null) return null;
                     return { gte: start, lte: end };
                 }
             }
         }
 
-        // Support decimal numbers
-        numValue = parseFloat(numValue as string);
-        if (isNaN(numValue)) return null;
+        const parsed = this.#parseNumericValue(numValue);
+        if (parsed == null) return null;
 
-        return { [prismaOp]: numValue };
+        return { [prismaOp]: parsed };
+    }
+
+    /**
+     * Parse a numeric string, returning BigInt for integers beyond safe range
+     */
+    #parseNumericValue(value: string): number | bigint | null {
+        if (value.includes('.')) {
+            const num = parseFloat(value);
+            return isNaN(num) ? null : num;
+        }
+        const num = Number(value);
+        if (isNaN(num)) return null;
+        if (!Number.isSafeInteger(num)) {
+            try { return BigInt(value); } catch { return null; }
+        }
+        return num;
     }
 
     /**
@@ -2048,7 +2066,7 @@ class QueryBuilder {
      * Handle Prisma errors and convert to standardized error responses
      */
     static errorHandler(error: any, data: Record<string, unknown> = {}): QueryErrorResponse {
-        console.error(error);
+        Logger.error(error);
 
         // Default values
         let statusCode: number = error.status_code || 500;

package/src/plugins/response.ts

@@ -2,6 +2,7 @@ import { FastifyPluginAsync, FastifyReply, FastifyRequest } from 'fastify';
 import fp from 'fastify-plugin';
 import { ErrorResponse, ErrorBasicResponse } from '../core/errors';
 import { LanguageDict } from '../core/i18n';
+import { Logger } from '../utils/Logger';
 import type { ListMeta } from '../types';
 
 /**
@@ -37,7 +38,7 @@ const responsePlugin: FastifyPluginAsync = async (fastify) => {
         const request = this.request;
         const language = request?.language || 'en_US';
         const error = new ErrorResponse(statusCode, message, data as Record<string, unknown> | null);
-        console.error(`Error ${statusCode}: ${message}`);
+        Logger.error(message, { statusCode });
         return this.code(statusCode).send(error.toJSON(language));
     });
 
@@ -72,7 +73,7 @@ const responsePlugin: FastifyPluginAsync = async (fastify) => {
                 ? 'Something went wrong'
                 : err.message || String(error);
 
-        console.error(error);
+        Logger.error(error);
         return reply.code(status).send({ status_code: status, message });
     });
 };

package/src/utils/Logger.ts

@@ -0,0 +1,157 @@
+import { appendFileSync, mkdirSync, existsSync } from 'fs';
+import path from 'path';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type LogLevel = 'essential' | 'fine' | 'finest';
+
+// ── Level Config ─────────────────────────────────────────────────────────────
+
+const LEVELS: LogLevel[] = ['essential', 'fine', 'finest'];
+
+function parseLevel(value: string | undefined): LogLevel {
+    if (value && LEVELS.includes(value as LogLevel)) {
+        return value as LogLevel;
+    }
+    return 'essential';
+}
+
+// ── State ────────────────────────────────────────────────────────────────────
+
+const _level: LogLevel = parseLevel(process.env.LOG_LEVEL);
+const _silent: boolean = process.env.NODE_ENV === 'test';
+const _logDir: string = process.env.LOG_DIR ?? 'logs';
+
+// ── File Writing ─────────────────────────────────────────────────────────────
+
+let _dirChecked = false;
+
+function ensureLogDir(): void {
+    if (_dirChecked || !_logDir) return;
+    const dir = path.isAbsolute(_logDir) ? _logDir : path.join(process.cwd(), _logDir);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    _dirChecked = true;
+}
+
+function writeToFile(filename: string, line: string): void {
+    if (!_logDir) return;
+    try {
+        ensureLogDir();
+        const dir = path.isAbsolute(_logDir) ? _logDir : path.join(process.cwd(), _logDir);
+        appendFileSync(path.join(dir, filename), line + '\n');
+    } catch {
+        // Silently ignore file write failures — don't crash the app for logging
+    }
+}
+
+// ── Formatting ───────────────────────────────────────────────────────────────
+
+function timestamp(): string {
+    return new Date().toISOString();
+}
+
+function formatData(data: unknown[]): string {
+    if (data.length === 0) return '';
+    const parts = data.map(d => {
+        if (d === null || d === undefined) return String(d);
+        if (typeof d === 'object') {
+            try { return JSON.stringify(d); } catch { return String(d); }
+        }
+        return String(d);
+    });
+    return ' ' + parts.join(' ');
+}
+
+function formatDataPretty(data: unknown[]): string {
+    if (data.length === 0) return '';
+    const parts = data.map(d => {
+        if (d === null || d === undefined) return String(d);
+        if (typeof d === 'object') {
+            try { return JSON.stringify(d, null, 2); } catch { return String(d); }
+        }
+        return String(d);
+    });
+    return '\n' + parts.join('\n');
+}
+
+function formatError(error: Error | string | unknown): { message: string; toString: string; stack: string } {
+    if (error instanceof Error) {
+        return {
+            message: error.message,
+            toString: error.toString(),
+            stack: error.stack || error.toString(),
+        };
+    }
+    const str = String(error);
+    return { message: str, toString: str, stack: str };
+}
+
+// ── Logger ───────────────────────────────────────────────────────────────────
+
+export const Logger = {
+    log(message: string, ...data: unknown[]): void {
+        if (_silent) return;
+
+        let output: string;
+        switch (_level) {
+            case 'essential':
+                output = `[${timestamp()}] [LOG] ${message}`;
+                break;
+            case 'fine':
+                output = `[${timestamp()}] [LOG] ${message}${formatData(data)}`;
+                break;
+            case 'finest':
+                output = `[${timestamp()}] [LOG] ${message}${formatDataPretty(data)}`;
+                break;
+        }
+
+        console.log(output);
+        writeToFile('app.log', output);
+    },
+
+    warn(message: string, ...data: unknown[]): void {
+        if (_silent) return;
+
+        let output: string;
+        switch (_level) {
+            case 'essential':
+                output = `[${timestamp()}] [WARN] ${message}`;
+                break;
+            case 'fine':
+                output = `[${timestamp()}] [WARN] ${message}${formatData(data)}`;
+                break;
+            case 'finest':
+                output = `[${timestamp()}] [WARN] ${message}${formatDataPretty(data)}`;
+                break;
+        }
+
+        console.warn(output);
+        writeToFile('app.log', output);
+    },
+
+    error(error: Error | string | unknown, ...data: unknown[]): void {
+        if (_silent) return;
+
+        const err = formatError(error);
+        let output: string;
+
+        switch (_level) {
+            case 'essential':
+                output = `[${timestamp()}] [ERROR] ${err.message}`;
+                break;
+            case 'fine':
+                output = `[${timestamp()}] [ERROR] ${err.toString}${formatData(data)}`;
+                break;
+            case 'finest':
+                output = `[${timestamp()}] [ERROR] ${err.stack}${formatDataPretty(data)}`;
+                break;
+        }
+
+        console.error(output);
+        writeToFile('error.log', output);
+    },
+};
+
+export default Logger;

package/src/utils/index.ts

@@ -4,6 +4,9 @@ export type { ServiceConfig, EndpointConfig, AuthConfig, RequestOptions, ApiResp
 export { Mailer } from './Mailer';
 export type { EmailConfig, EmailOptions, EmailAttachment, EmailResult } from './Mailer';
 
+export { Logger } from './Logger';
+export type { LogLevel } from './Logger';
+
 export const env = {
     isProduction: () => process.env.NODE_ENV === 'production',
     isDevelopment: () => __filename.endsWith('.ts') || process.env.NODE_ENV === 'development',