triva 0.0.2 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kris Powers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,416 @@
+<p align="center">
+
+  <p align="center">
+    <img style="border-radius: 10px; width: 120px; height 120px;" src=".github/assets/triva-logo.png" >
+  </P>
+
+  <h1 align="center">Triva</h1>
+
+  <p align="center">
+    A Node.js HTTP Server Framework built for enterprises
+  </p>
+
+  <p align="center">
+    Triva is an enterprise-grade Node.js HTTP framework with centralized configuration, database adapters, advanced middleware, and complete developer visibility.
+  </p>
+
+</p>
+
+> [!IMPORTANT]
+> **v0.3.0 - Pre Release**
+>
+> This release is intended solely for the **continued development & testing of Triva & its capabilities.** Expect **rapid updates containing bug fixes, feature reworks, & framekwork optimization** going forward, until the official release of v1.0.0 and onward.
+>
+> During the **Pre-release** phase, a wide range of efforts to build a **user-friendly documentation interface** will also be in the works. Until the release of that interface, it's recommended that developers testing Triva refer to the docs found below.
+>
+>**If you're looking to contribute in any capacity, please feel free to submit a pull request or issue ticket for review.**
+>
+>
+
+## ✨ Features
+
+- 🎯 **Centralized Configuration** - Everything configured in `build()`
+- 🗄️ **Multiple Databases** - Memory, MongoDB, Redis, PostgreSQL, MySQL
+- 📦 **Auto-Detection** - Helpful errors if database packages aren't installed
+- 🚀 **Zero Dependencies** (core) - Optional database drivers as needed
+- 🛡️ **Advanced Throttling** - Sliding window, burst protection, auto-ban
+- 📊 **Comprehensive Logging** - Request logs with cookies, UA data
+- ⚡ **Built-in Caching** - Works with any supported database
+- 🔍 **Error Tracking** - Automatic error capture with full context
+- 🍪 **Cookie Parser** - Parse and set cookies easily
+- 📥 **File Operations** - Download and send files
+- 🌐 **JSONP Support** - Cross-domain API calls
+- ⚙️ **Custom Middleware** - Full Express-style middleware support
+
+## 📦 Installation
+
+```bash
+npm install triva
+
+# Optional: Install database driver if needed
+npm install mongodb  # For MongoDB
+npm install redis    # For Redis
+npm install pg       # For PostgreSQL
+npm install mysql2   # For MySQL
+```
+
+## 🚀 Quick Start
+
+```javascript
+import { build, get, listen } from 'triva';
+
+// All configuration in one place!
+await build({
+  env: 'development',
+
+  cache: {
+    type: 'memory',
+    retention: 600000
+  },
+
+  throttle: {
+    limit: 100,
+    window_ms: 60000
+  }
+});
+
+get('/', (req, res) => {
+  res.json({ message: 'Hello World!' });
+});
+
+listen(3000);
+```
+
+## 🎯 Centralized Configuration
+
+Everything is configured in `build()`:
+
+```javascript
+await build({
+  env: 'development',
+
+  // Cache Configuration
+  cache: {
+    type: 'mongodb',        // memory, mongodb, redis, postgresql, mysql
+    retention: 600000,       // 10 minutes
+    limit: 10000,
+
+    database: {
+      uri: 'mongodb://localhost:27017',
+      database: 'triva',
+      collection: 'cache'
+    }
+  },
+
+  // Throttle Configuration
+  throttle: {
+    limit: 100,
+    window_ms: 60000,
+    burst_limit: 20,
+    burst_window_ms: 1000,
+    ban_threshold: 5,
+    ban_ms: 300000
+  },
+
+  // Log Retention
+  retention: {
+    enabled: true,
+    maxEntries: 10000
+  },
+
+  // Error Tracking
+  errorTracking: {
+    enabled: true,
+    maxEntries: 5000
+  }
+});
+```
+
+## 🗄️ Database Support
+
+### Memory (Built-in)
+```javascript
+await build({
+  cache: { type: 'memory' }
+});
+```
+
+### MongoDB
+```bash
+npm install mongodb
+```
+
+```javascript
+await build({
+  cache: {
+    type: 'mongodb',
+    database: {
+      uri: 'mongodb://localhost:27017',
+      database: 'triva'
+    }
+  }
+});
+```
+
+### Redis
+```bash
+npm install redis
+```
+
+```javascript
+await build({
+  cache: {
+    type: 'redis',
+    database: {
+      host: 'localhost',
+      port: 6379
+    }
+  }
+});
+```
+
+### PostgreSQL
+```bash
+npm install pg
+```
+
+```javascript
+await build({
+  cache: {
+    type: 'postgresql',
+    database: {
+      host: 'localhost',
+      port: 5432,
+      database: 'triva',
+      user: 'postgres',
+      password: 'password'
+    }
+  }
+});
+```
+
+### MySQL
+```bash
+npm install mysql2
+```
+
+```javascript
+await build({
+  cache: {
+    type: 'mysql',
+    database: {
+      host: 'localhost',
+      port: 3306,
+      database: 'triva',
+      user: 'root',
+      password: 'password'
+    }
+  }
+});
+```
+
+**Helpful Errors:**
+```
+❌ MongoDB package not found.
+
+   Install it with: npm install mongodb
+
+   Then restart your server.
+```
+
+## 📖 Core Features
+
+### Routing
+
+```javascript
+import { get, post, put, delete as del } from 'triva';
+
+get('/users', (req, res) => {
+  res.json({ users: [] });
+});
+
+get('/users/:id', (req, res) => {
+  const { id } = req.params;
+  res.json({ userId: id });
+});
+
+post('/users', async (req, res) => {
+  const data = await req.json();
+  res.json({ created: true });
+});
+```
+
+### Cookies
+
+```javascript
+import { use, cookieParser } from 'triva';
+
+use(cookieParser());
+
+get('/login', (req, res) => {
+  res.cookie('sessionId', 'abc123', {
+    httpOnly: true,
+    maxAge: 3600000
+  });
+  res.json({ success: true });
+});
+
+get('/profile', (req, res) => {
+  const sessionId = req.cookies.sessionId;
+  res.json({ sessionId });
+});
+```
+
+### File Operations
+
+```javascript
+// Download file
+get('/download', (req, res) => {
+  res.download('/path/to/file.pdf', 'report.pdf');
+});
+
+// Send file
+get('/view', (req, res) => {
+  res.sendFile('/path/to/document.pdf');
+});
+```
+
+### JSONP
+
+```javascript
+get('/api/data', (req, res) => {
+  res.jsonp({ users: ['Alice', 'Bob'] });
+});
+```
+
+### Custom Middleware
+
+```javascript
+use((req, res, next) => {
+  console.log(`${req.method} ${req.url}`);
+  next();
+});
+```
+
+### Logging
+
+```javascript
+import { log } from 'triva';
+
+// Get logs
+const logs = await log.get({ limit: 100 });
+
+// Export logs
+await log.export('all', 'my-logs.json');
+
+// Get stats
+const stats = await log.getStats();
+```
+
+### Error Tracking
+
+```javascript
+import { errorTracker } from 'triva';
+
+// Get errors
+const errors = await errorTracker.get({ severity: 'critical' });
+
+// Get stats
+const stats = await errorTracker.getStats();
+```
+
+## 📊 Complete Example
+
+```javascript
+import {
+  build,
+  use,
+  get,
+  post,
+  listen,
+  cookieParser,
+  log
+} from 'triva';
+
+// Centralized configuration
+await build({
+  env: 'production',
+
+  cache: {
+    type: 'redis',
+    database: {
+      host: process.env.REDIS_HOST,
+      port: 6379
+    }
+  },
+
+  throttle: {
+    limit: 100,
+    window_ms: 60000
+  },
+
+  retention: {
+    enabled: true,
+    maxEntries: 50000
+  }
+});
+
+// Middleware
+use(cookieParser());
+
+// Routes
+get('/', (req, res) => {
+  res.json({ status: 'ok', cookies: req.cookies });
+});
+
+get('/api/users/:id', (req, res) => {
+  res.json({ userId: req.params.id });
+});
+
+post('/api/users', async (req, res) => {
+  const data = await req.json();
+  res.status(201).json({ created: true, data });
+});
+
+get('/download/report', (req, res) => {
+  res.download('./reports/annual-report.pdf');
+});
+
+get('/admin/logs/export', async (req, res) => {
+  const result = await log.export({ limit: 1000 });
+  res.json({ exported: result.count });
+});
+
+// Start server
+listen(process.env.PORT || 3000, () => {
+  console.log('Server running');
+});
+```
+
+## 🔧 Response Methods
+
+```javascript
+res.json(data)                    // Send JSON
+res.send(data)                    // Auto-detect (HTML/JSON/text)
+res.html(html)                    // Send HTML
+res.status(code)                  // Set status code
+res.header(name, value)           // Set header
+res.redirect(url, code)           // Redirect
+res.jsonp(data)                   // Send JSONP
+res.download(path, filename)      // Download file
+res.sendFile(path, options)       // Send file
+res.cookie(name, value, options)  // Set cookie
+res.clearCookie(name)             // Clear cookie
+```
+
+## ⚡ Performance
+
+- **Memory**: Fastest (built-in)
+- **Redis**: Fastest (external DB)
+- **MongoDB**: Fast (document store)
+- **PostgreSQL**: Fast (ACID compliance)
+- **MySQL**: Fast (traditional)
+
+## 📄 License
+
+MIT

package/index.d.ts

@@ -0,0 +1,91 @@
+// Triva Type Definitions
+import { IncomingMessage, ServerResponse } from 'http';
+
+export interface ServerOptions {
+  env?: 'development' | 'production';
+}
+
+export interface CookieOptions {
+  maxAge?: number;
+  expires?: Date | string;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: 'Strict' | 'Lax' | 'None' | boolean;
+  path?: string;
+  domain?: string;
+}
+
+export interface SendFileOptions {
+  contentType?: string;
+  headers?: Record<string, string>;
+}
+
+export interface ResponseHelpers extends ServerResponse {
+  status(code: number): this;
+  header(name: string, value: string): this;
+  json(data: any): this;
+  send(data: any): this;
+  html(html: string): this;
+  redirect(url: string, code?: number): this;
+  jsonp(data: any, callbackParam?: string): this;
+  download(filepath: string, filename?: string): this;
+  sendFile(filepath: string, options?: SendFileOptions): this;
+  cookie(name: string, value: string, options?: CookieOptions): this;
+  clearCookie(name: string, options?: CookieOptions): this;
+}
+
+export interface RequestContext {
+  req: IncomingMessage;
+  res: ResponseHelpers;
+  params: Record<string, string>;
+  query: Record<string, string | string[]>;
+  pathname: string;
+  cookies: Record<string, string>;
+  json(): Promise<any>;
+  text(): Promise<string>;
+}
+
+export type RouteHandler = (req: RequestContext, res: ResponseHelpers) => void | Promise<void>;
+export type MiddlewareFunction = (req: IncomingMessage, res: ServerResponse, next: (err?: Error) => void) => void;
+
+export function build(options?: ServerOptions): void;
+export function middleware(options?: any): void;
+export function use(middleware: MiddlewareFunction): void;
+export function get(pattern: string, handler: RouteHandler): void;
+export function post(pattern: string, handler: RouteHandler): void;
+export function put(pattern: string, handler: RouteHandler): void;
+export function patch(pattern: string, handler: RouteHandler): void;
+export { del as delete };
+export function del(pattern: string, handler: RouteHandler): void;
+export function listen(port: number, callback?: () => void): any;
+export function setErrorHandler(handler: (err: Error, req: IncomingMessage, res: ServerResponse) => void): void;
+export function setNotFoundHandler(handler: (req: IncomingMessage, res: ServerResponse) => void): void;
+
+export const log: {
+  get(filter?: any): Promise<any[]>;
+  getStats(): Promise<any>;
+  clear(): Promise<any>;
+  search(query: string): Promise<any[]>;
+  export(filter?: any, filename?: string): Promise<any>;
+};
+
+export const cache: {
+  get(key: string): Promise<any>;
+  set(key: string, value: any, ttl?: number): Promise<boolean>;
+  delete(key: string): Promise<boolean>;
+  clear(): Promise<number>;
+  stats(): Promise<any>;
+};
+
+export const errorTracker: {
+  configure(options: any): any;
+  capture(error: Error, context?: any): Promise<any>;
+  get(filter?: any): Promise<any[]>;
+  getById(id: string): Promise<any>;
+  resolve(id: string): Promise<any>;
+  getStats(): Promise<any>;
+  clear(): Promise<any>;
+};
+
+export function configCache(options: any): void;
+export function cookieParser(secret?: string): MiddlewareFunction;

package/lib/cache.js

@@ -0,0 +1,112 @@
+/*!
+ * Triva - Cache Manager with Database Adapters
+ * Copyright (c) 2026 Kris Powers
+ * License MIT
+ */
+
+'use strict';
+
+import { createAdapter } from './db-adapters.js';
+
+/* ---------------- Cache Manager ---------------- */
+class CacheManager {
+  constructor() {
+    this.adapter = null;
+    this.config = {
+      enabled: true,
+      type: 'memory',
+      retention: 10 * 60 * 1000, // 10 minutes default
+      limit: 100000
+    };
+  }
+
+  async configure(options = {}) {
+    this.config = {
+      ...this.config,
+      enabled: options.cache_data !== false,
+      type: options.cache_type || options.type || 'memory',
+      retention: options.cache_retention || options.retention || this.config.retention,
+      limit: options.cache_limit || options.limit || this.config.limit
+    };
+
+    // Create adapter
+    try {
+      const adapterConfig = options.database || options.db || {};
+      this.adapter = createAdapter(this.config.type, adapterConfig);
+      await this.adapter.connect();
+    } catch (error) {
+      console.error('❌ Cache adapter error:', error.message);
+      throw error;
+    }
+
+    return this;
+  }
+
+  async get(key) {
+    if (!this.config.enabled || !this.adapter) return null;
+    return await this.adapter.get(key);
+  }
+
+  async set(key, value, ttl = null) {
+    if (!this.config.enabled || !this.adapter) return false;
+    const actualTtl = ttl !== null ? ttl : this.config.retention;
+    return await this.adapter.set(key, value, actualTtl);
+  }
+
+  async delete(key) {
+    if (!this.adapter) return false;
+    return await this.adapter.delete(key);
+  }
+
+  async has(key) {
+    if (!this.adapter) return false;
+    return await this.adapter.has(key);
+  }
+
+  async clear() {
+    if (!this.adapter) return 0;
+    return await this.adapter.clear();
+  }
+
+  async keys(pattern = null) {
+    if (!this.adapter) return [];
+    return await this.adapter.keys(pattern);
+  }
+
+  async size() {
+    if (!this.adapter) return 0;
+    const allKeys = await this.adapter.keys();
+    return allKeys.length;
+  }
+
+  async stats() {
+    const size = await this.size();
+    
+    return {
+      size,
+      maxSize: this.config.limit,
+      active: size,
+      config: {
+        enabled: this.config.enabled,
+        type: this.config.type,
+        retention: this.config.retention,
+        limit: this.config.limit
+      }
+    };
+  }
+
+  shutdown() {
+    if (this.adapter) {
+      this.adapter.disconnect();
+    }
+  }
+}
+
+/* ---------------- Export Singleton ---------------- */
+const cache = new CacheManager();
+
+function configCache(options) {
+  return cache.configure(options);
+}
+
+export { cache, configCache, CacheManager };