bunsane 0.1.0 → 0.1.2

package/database/DatabaseHelper.ts

@@ -2,6 +2,34 @@ import db from "database";
 import { logger as MainLogger } from "core/Logger";
 const logger = MainLogger.child({ scope: "DatabaseHelper" });
 
+const BUNSANE_RELATION_TYPED_COLUMN = process.env.BUNSANE_RELATION_TYPED_COLUMN === 'true' || false;
+
+const validateIdentifier = (str: string, maxLength: number = 64): string => {
+    if (!str || typeof str !== 'string' || str.length === 0 || str.length > maxLength) {
+        throw new Error(`Invalid identifier: ${str}`);
+    }
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(str)) {
+        throw new Error(`Invalid identifier format: ${str}`);
+    }
+    return str;
+};
+
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+const retryWithBackoff = async (fn: () => Promise<void>, maxRetries: number = 3, baseDelay: number = 1000) => {
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            await fn();
+            return;
+        } catch (error) {
+            if (i === maxRetries - 1) throw error;
+            const delay = baseDelay * Math.pow(2, i);
+            logger.warn(`Operation failed, retrying in ${delay}ms: ${error}`);
+            await sleep(delay);
+        }
+    }
+};
+
 export const GetSchema = async () => {
     const dbSchema = await db`SELECT table_name 
         FROM information_schema.tables 
@@ -20,60 +48,145 @@ export const HasValidBaseTable = async (): Promise<boolean> => {
 
 export const PrepareDatabase = async () => {
     logger.trace(`Initializing Database.`);
-    await SetupDatabaseExtensions();
-    await CreateEntityTable();
-    await CreateComponentTable();
-    await CreateEntityComponentTable();
+    try {
+        await SetupDatabaseExtensions();
+    } catch (error) {
+        logger.error(`Failed to setup database extensions: ${error}`);
+        throw error;
+    }
+    try {
+        await CreateEntityTable();
+    } catch (error) {
+        logger.error(`Failed to create entity table: ${error}`);
+        throw error;
+    }
+    try {
+        await CreateComponentTable();
+    } catch (error) {
+        logger.error(`Failed to create component table: ${error}`);
+        throw error;
+    }
+    try {
+        await CreateEntityComponentTable();
+    } catch (error) {
+        logger.error(`Failed to create entity component table: ${error}`);
+        throw error;
+    }
 }
 
+export const GetDatabaseDataSize = async () => {
+    const result = await db`SELECT
+        relname AS table_name,
+        pg_size_pretty(pg_total_relation_size(oid)) AS total_size_pretty,
+        ROUND(pg_total_relation_size(oid) / (1024.0 * 1024.0), 2) AS total_size_mb
+    FROM
+        pg_class
+    WHERE
+        relkind = 'r' -- 'r' for regular table, 'p' for partitioned table
+        AND relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'public') -- Or your specific schema
+    ORDER BY
+        pg_total_relation_size(oid) DESC;`;
+    return result;
+}
+
+
 export const SetupDatabaseExtensions = async () => {
-    return new Promise(async resolve => {
-        // await db`CREATE EXTENSION IF NOT EXISTS "uuid-ossp";`;
-        return resolve(true);
-    })
+    // await db`CREATE EXTENSION IF NOT EXISTS "uuid-ossp";`;
 }
 
 export const CreateEntityTable = async () => {
-    return new Promise(async resolve => {
-        await db`CREATE TABLE IF NOT EXISTS entities (
-            id UUID PRIMARY KEY,
-            created_at TIMESTAMP DEFAULT NOW(),
-            updated_at TIMESTAMP DEFAULT NOW()
-        );`;
-        return resolve(true);
-    });
+    await db`CREATE TABLE IF NOT EXISTS entities (
+        id UUID PRIMARY KEY,
+        created_at TIMESTAMP DEFAULT NOW(),
+        updated_at TIMESTAMP DEFAULT NOW(),
+        deleted_at TIMESTAMP
+    );`;
 }
 
-export const CreateComponentTable = () => {
-    return new Promise(async resolve => {
-        await db`CREATE TABLE IF NOT EXISTS components (
-            id UUID,
-            entity_id UUID REFERENCES entities(id),
-            type_id varchar(64) NOT NULL,
-            name varchar(128),
-            data jsonb,
-            created_at TIMESTAMP DEFAULT NOW(),
-            updated_at TIMESTAMP DEFAULT NOW(),
-            PRIMARY KEY (id, type_id, entity_id)
-        ) PARTITION BY LIST (type_id);`;
-        await db`CREATE INDEX IF NOT EXISTS idx_components_entity_id ON components (entity_id);`
-        await db`CREATE INDEX IF NOT EXISTS idx_components_type_id ON components (type_id);`
-        await db`CREATE INDEX IF NOT EXISTS idx_components_data_gin ON components USING GIN (data);`
-        return resolve(true);
-    });
+export const CreateComponentTable = async () => {
+    await db`CREATE TABLE IF NOT EXISTS components (
+        id UUID,
+        entity_id UUID REFERENCES entities(id),
+        type_id varchar(64) NOT NULL,
+        name varchar(128),
+        data jsonb,
+        created_at TIMESTAMP DEFAULT NOW(),
+        updated_at TIMESTAMP DEFAULT NOW(),
+        deleted_at TIMESTAMP,
+        PRIMARY KEY (id, type_id, entity_id)
+    ) PARTITION BY LIST (type_id);`;
+    await db`CREATE INDEX IF NOT EXISTS idx_components_entity_id ON components (entity_id);`
+    await db`CREATE INDEX IF NOT EXISTS idx_components_type_id ON components (type_id);`
+    await db`CREATE INDEX IF NOT EXISTS idx_components_data_gin ON components USING GIN (data);`
+
+    // Phase 2A: Add composite indexes for sorting optimization
+    await db`CREATE INDEX IF NOT EXISTS idx_components_entity_type_deleted ON components (entity_id, type_id, deleted_at);`
+    await db`CREATE INDEX IF NOT EXISTS idx_components_type_deleted ON components (type_id, deleted_at) WHERE deleted_at IS NULL;`
+    await db`CREATE INDEX IF NOT EXISTS idx_components_deleted_entity ON components (deleted_at, entity_id) WHERE deleted_at IS NULL;`
+}
+
+export const UpdateComponentIndexes = async (table_name: string, indexedProperties: string[]) => {
+    try {
+        table_name = validateIdentifier(table_name);
+        indexedProperties = indexedProperties.map(prop => validateIdentifier(prop));
+        logger.trace(`Updating indexes for component table: ${table_name}`);
+        const indexes_list = await db.unsafe(`
+            SELECT indexname 
+            FROM pg_indexes 
+            WHERE tablename = '${table_name}'
+        `);
+        const existingIndexes = indexes_list.map((row: any) => row.indexname);
+        const addedIndexes = new Set<string>();
+
+        // Check and create indexes for any new indexed properties
+        if (indexedProperties && indexedProperties.length > 0) {
+            for (const prop of indexedProperties) {
+                const indexName = `idx_${table_name}_${prop}_gin`;
+                if (!existingIndexes.includes(indexName)) {
+                    logger.trace(`Creating missing index ${indexName} for property ${prop}`);
+                    await retryWithBackoff(async () => {
+                        await db.unsafe(`CREATE INDEX CONCURRENTLY IF NOT EXISTS ${indexName} ON ${table_name} USING GIN ((data->'${prop}'))`);
+                    });
+                    addedIndexes.add(indexName);
+                } else {
+                    logger.trace(`Index ${indexName} for property ${prop} already exists`);
+                }
+            }
+        }
+
+        // Remove indexes for properties that are no longer indexed
+        for (const index of existingIndexes) {
+            const match = index.match(new RegExp(`^idx_${table_name}_(.*)_gin$`));
+            if (match) {
+                const prop = match[1];
+                if (!indexedProperties.includes(prop) && !addedIndexes.has(index)) {
+                    await retryWithBackoff(async () => {
+                        await db.unsafe(`DROP INDEX CONCURRENTLY IF EXISTS ${index}`);
+                    });
+                    logger.info(`Dropped obsolete index ${index} for property ${prop}`);
+                }
+            }
+        }
+    } catch (error) {
+        logger.error(`Failed to update component indexes for ${table_name}: ${error}`);
+        throw error;
+    }
 }
 
 
 export const CreateComponentPartitionTable = async (comp_name: string, type_id: string, indexedProperties?: string[]) => {
     try {
+        comp_name = validateIdentifier(comp_name);
+        // type_id is a value, not identifier, so no validation
+        if (indexedProperties) {
+            indexedProperties = indexedProperties.map(prop => validateIdentifier(prop));
+        }
         logger.trace(`Attempt adding partition table for component: ${comp_name}`);
         const table_name = `components_${comp_name.toLowerCase().replace(/\s+/g, '_')}`;
         logger.trace(`Checking for existing partition table: ${table_name}`);
-        const existingPartition = await db`
-            SELECT 1 FROM information_schema.tables 
-            WHERE table_name = ${table_name} 
-            AND table_schema = 'public'
-        `;
+        const existingPartition = await db.unsafe(`SELECT 1 FROM information_schema.tables 
+            WHERE table_name = '${table_name}' 
+            AND table_schema = 'public'`);
         logger.trace(`Existing partition check result: ${existingPartition.length > 0 ? 'found' : 'not found'}`);
 
         if (existingPartition.length > 0) {
@@ -82,47 +195,54 @@ export const CreateComponentPartitionTable = async (comp_name: string, type_id:
         }
         logger.trace(`Creating partition table: ${table_name}`);
 
-        await db.unsafe(`CREATE TABLE IF NOT EXISTS ${table_name}
+        await retryWithBackoff(async () => {
+            await db.unsafe(`CREATE TABLE IF NOT EXISTS ${table_name}
                 PARTITION OF components
-                FOR VALUES IN ('${type_id}');`);
-        
-        if (indexedProperties && indexedProperties.length > 0) {
-            for (const prop of indexedProperties) {
-                const indexName = `idx_${table_name}_${prop}`;
-                await db.unsafe(`CREATE INDEX IF NOT EXISTS ${indexName} ON ${table_name} USING GIN ((data->'${prop}'))`);
-                logger.trace(`Created index ${indexName} for property ${prop}`);
-            }
-        }
-        
+                FOR VALUES IN ('${type_id}')`);
+        });
         logger.trace(`Successfully created partition table: ${table_name}`);
+
+        if (BUNSANE_RELATION_TYPED_COLUMN && indexedProperties?.includes('value')) {
+            logger.trace(`Adding typed FK column for ${table_name}`);
+            await retryWithBackoff(async () => {
+                await db.unsafe(`ALTER TABLE ${table_name} ADD COLUMN IF NOT EXISTS fk_id UUID GENERATED ALWAYS AS ((data->>'value')::UUID) STORED`);
+            });
+            await retryWithBackoff(async () => {
+                await db.unsafe(`CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_${table_name}_fk_id ON ${table_name} (fk_id)`);
+            });
+            logger.trace(`Added fk_id column and index for ${table_name}`);
+        }
         
     } catch (error) {
         logger.error(`Failed to create component partition table for ${comp_name}: ${error}`);
-        throw error;
+        // Graceful degradation: log error without crashing
     }
 }
 
 export const DeleteComponentPartitionTable = async (comp_name: string) => {
     try {
+        comp_name = validateIdentifier(comp_name);
         const table_name = `components_${comp_name.toLowerCase().replace(/\s+/g, '_')}`;
 
-        const existingPartition = await db`
+        const existingPartition = await db.unsafe(`
             SELECT 1 FROM information_schema.tables
-            WHERE table_name = ${table_name}
+            WHERE table_name = '${table_name}'
             AND table_schema = 'public'
-        `;
+        `);
 
         if (existingPartition.length === 0) {
             logger.info(`Partition table ${table_name} does not exist`);
             return;
         }
 
-        await db.unsafe(`DROP TABLE IF EXISTS ${table_name}`);
+        await retryWithBackoff(async () => {
+            await db.unsafe(`DROP TABLE IF EXISTS ${table_name}`);
+        });
         logger.info(`Successfully deleted partition table: ${table_name}`);
 
     } catch (error) {
         logger.error(`Failed to delete component partition table for ${comp_name}: ${error}`);
-        throw error;
+        // Graceful degradation: log error without crashing
     }
 }
 
@@ -130,9 +250,14 @@ export const CreateEntityComponentTable = async () => {
     await db`CREATE TABLE IF NOT EXISTS entity_components (
         entity_id UUID REFERENCES entities(id),
         type_id VARCHAR(64) NOT NULL,
+        deleted_at TIMESTAMP,
         UNIQUE(entity_id, type_id)
     );`;
-    await db`CREATE INDEX IF NOT EXISTS idx_entity_components_entity_id ON entity_components (entity_id);`
-    await db`CREATE INDEX IF NOT EXISTS idx_entity_components_type_id ON entity_components (type_id);`
-    await db`CREATE INDEX IF NOT EXISTS idx_entity_components_type_entity ON entity_components (type_id, entity_id);`
+    await db`CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_entity_components_entity_id ON entity_components (entity_id);`
+    await db`CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_entity_components_type_id ON entity_components (type_id);`
+    await db`CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_entity_components_type_entity ON entity_components (type_id, entity_id);`
+
+    // Phase 2A: Add composite indexes for sorting optimization
+    await db`CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_entity_components_type_entity_deleted ON entity_components (type_id, entity_id, deleted_at);`
+    await db`CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_entity_components_deleted_type ON entity_components (deleted_at, type_id) WHERE deleted_at IS NULL;`
 }

package/database/index.ts

@@ -2,11 +2,11 @@ import {SQL} from "bun";
 import { logger } from "core/Logger";
 
 const db = new SQL({
-    url: `postgres://${process.env.POSTGRES_USER}:${process.env.POSTGRES_PASSWORD}@${process.env.POSTGRES_HOST}:5432/${process.env.POSTGRES_DB}`,
-    // Connection pool settings
-    max: 10, // Maximum connections in pool
-    idleTimeout: 0, // Close idle connections after 30s
-    maxLifetime: 0, // Connection lifetime in seconds (0 = forever)
+    url: `postgres://${process.env.POSTGRES_USER}:${process.env.POSTGRES_PASSWORD}@${process.env.POSTGRES_HOST}:${process.env.POSTGRES_PORT ?? "5432"}/${process.env.POSTGRES_DB}`,
+    // Connection pool settings - FIXED
+    max: parseInt(process.env.POSTGRES_MAX_CONNECTIONS ?? '20', 10), // Increased max connections
+    idleTimeout: 30000, // Close idle connections after 30s (was 0)
+    maxLifetime: 600000, // Connection lifetime 10 minutes (was 0 = forever)
     connectionTimeout: 30, // Timeout when establishing new connections
     onclose: (err) => {
         if (err) {

package/database/sqlHelpers.ts

@@ -0,0 +1,7 @@
+import { sql } from 'bun';
+
+export function inList<T>(values: T[], paramIndex: number): { sql: string, params: any[], newParamIndex: number } {
+  if (values.length === 0) return { sql: '()', params: [], newParamIndex: paramIndex };
+  const placeholders = Array.from({length: values.length}, (_, i) => `$${paramIndex + i}`).join(', ');
+  return { sql: `(${placeholders})`, params: values, newParamIndex: paramIndex + values.length };
+}

package/docs/README.md

@@ -0,0 +1,149 @@
+# BunSane Framework Documentation
+
+Welcome to the official documentation for **BunSane** - a batteries-included TypeScript API framework built on the Bun runtime.
+
+## 🎯 What Makes BunSane Special?
+
+BunSane revolutionizes API development by combining the power of Entity-Component-System (ECS) architecture with modern TypeScript. Built specifically for Bun's high-performance runtime, it provides a flexible foundation for building scalable applications.
+
+### Key Differentiators
+
+- **ECS Architecture**: Flexible data modeling without traditional ORM limitations
+- **Type-Safe Everything**: Full TypeScript integration with compile-time guarantees
+- **Bun-Native Performance**: Optimized for Bun's speed and efficiency
+- **Component-Based Design**: Build complex entities from reusable components
+- **Built-in GraphQL Support**: GraphQL integration with Yoga
+
+## 🚀 Quick Start
+
+Get up and running in minutes:
+
+```bash
+# Install BunSane
+bun install bunsane
+
+# Create your first entity
+import { Entity, Component, CompData, BaseComponent } from 'bunsane';
+
+@Component
+class UserProfile extends BaseComponent {
+  @CompData()
+  name: string = '';
+
+  @CompData()
+  email: string = '';
+}
+
+// Create and save an entity
+const user = Entity.Create();
+user.add(UserProfile, { name: 'John Doe', email: 'john@example.com' });
+await user.save();
+```
+
+## 📚 Core Architecture
+
+BunSane is built around four fundamental concepts:
+
+### 1. **Entities** - Your Data Objects
+Entities are the core data containers in BunSane. Unlike traditional objects, entities are composed of multiple components, allowing for flexible and dynamic data structures.
+
+### 2. **Components** - Data Building Blocks
+Components are pure data structures that define specific aspects of your entities. They're decorated with `@CompData()` and automatically persisted to PostgreSQL.
+
+### 3. **ArcheTypes** - Entity Templates
+ArcheTypes provide reusable templates for creating entities with predefined component sets, reducing code duplication and ensuring consistency.
+
+### 4. **Services** - Business Logic
+Services contain your business logic and can integrate with GraphQL resolvers for API endpoints.
+
+## 🔧 Features
+
+- **Lifecycle Hooks**: React to entity creation, updates, and deletion
+- **Query System**: Type-safe querying with filtering
+- **Component Registry**: Automatic component discovery and registration
+- **Entity Caching**: Built-in caching for improved performance
+- **GraphQL Integration**: Basic GraphQL support with Yoga
+- **File Upload Support**: Basic file upload handling
+- **Background Tasks**: Simple scheduled task support
+- **Request Context**: Context management for requests
+
+## 📖 Documentation Sections
+
+### Getting Started
+- **[Installation Guide](getting-started.md)** - Setup and configuration
+- **[Interactive Demo](examples/interactive-demo.md)** - Live code examples
+- **[Code Examples](examples/code-examples.md)** - Complete runnable examples
+
+### Core Concepts
+- **[Entities](core-concepts/entity.md)** - Entity lifecycle and management
+- **[Components](core-concepts/components.md)** - Component definitions and patterns
+- **[ArcheTypes](core-concepts/archetypes.md)** - Entity templates and reuse
+- **[Services](core-concepts/services.md)** - Business logic layer
+- **[Query System](core-concepts/query.md)** - Database querying
+- **[Hooks](core-concepts/hooks.md)** - Lifecycle events and customization
+
+### Advanced Features
+- **[File Uploads](advanced/uploads.md)** - File handling and storage
+- **[Background Tasks](advanced/scheduler.md)** - Job scheduling and processing
+- **[Performance](advanced/performance.md)** - Optimization strategies
+- **[Security](advanced/security.md)** - Authentication and authorization
+
+### API Reference
+- **[Core API](api/core.md)** - Entity, Component, ArcheType classes
+- **[Query API](api/query.md)** - Database operations and querying
+- **[Service API](api/service.md)** - Business logic services
+- **[Hooks API](api/hooks.md)** - Event system and lifecycle
+- **[Upload API](api/upload.md)** - File management
+- **[Scheduler API](api/scheduler.md)** - Background job management
+- **[Performance Guide](api/performance.md)** - Optimization techniques
+- **[Testing Guide](api/testing.md)** - Testing patterns and best practices
+
+## 🌟 Real-World Use Cases
+
+BunSane excels in applications requiring:
+
+- **Content Management Systems** - Flexible content modeling with components
+- **E-commerce Platforms** - Complex product catalogs with dynamic attributes
+- **Business Applications** - Multi-tenant architectures with customizable entities
+- **Data-Intensive Applications** - Structured data with relationships
+
+## 🤝 Community & Support
+
+- **GitHub**: [yaaruu/bunsane](https://github.com/yaaruu/bunsane)
+- **Issues**: [Report bugs or request features](https://github.com/yaaruu/bunsane/issues)
+- **Discussions**: [Community discussions](https://github.com/yaaruu/bunsane/discussions)
+
+## 📈 Project Status
+
+**Current Version**: 0.1.0 (Development)
+**Documentation**: ✅ Complete API Reference
+**Status**: Actively developed
+**License**: MIT
+
+### ✅ Implemented Features
+- **Core ECS Architecture**: Entity, Component, ArcheType system
+- **Database Integration**: PostgreSQL with automatic schema management
+- **Query System**: Type-safe database querying
+- **Hook System**: Entity and component lifecycle events
+- **Service Layer**: Business logic organization
+- **Basic GraphQL**: GraphQL integration with static schema
+- **File Upload**: Basic file upload handling
+- **Background Tasks**: Simple task scheduling
+- **Component Registry**: Automatic component discovery
+
+### 🚧 In Development
+- **Advanced GraphQL**: Dynamic schema generation from services
+- **Full-Text Search**: Search capabilities across entities
+- **Real-time Features**: WebSocket support for live updates
+- **Advanced Caching**: Distributed caching strategies
+- **OpenAPI Integration**: Automatic API documentation
+
+### 📋 Planned Features
+- **Custom Component Tables**: Direct column storage instead of JSONB
+- **Filesystem Integration**: Advanced file management
+- **Field Constraints**: Data validation and constraints
+- **OpenAPI Specification**: Automatic API spec generation
+
+---
+
+*Ready to build something amazing? Let's get started!* 🚀

package/docs/_coverpage.md

@@ -0,0 +1,36 @@
+# BunSane Framework
+
+> A batteries-included TypeScript API framework for Bun
+
+[Get Started](getting-started.md)
+[GitHub](https://github.com/yaaruu/bunsane)
+
+## 🚀 What is BunSane?
+
+BunSane is a modern, high-performance TypeScript framework built on Bun runtime that provides:
+
+- **Entity-Component-System (ECS)** architecture for flexible data modeling
+- **Basic GraphQL Integration** with Yoga
+- **PostgreSQL integration** with automatic schema management
+- **Lifecycle hooks** for business logic integration
+- **File upload system** with basic handling
+
+## ⚡ Key Features
+
+- **Type-Safe**: Full TypeScript support with compile-time guarantees
+- **Performance Optimized**: Built for speed with Bun's native performance
+- **Component-Based**: Flexible entity composition with reusable components
+- **Hook System**: Event-driven architecture for entity lifecycle
+- **Extensible**: Clean architecture for adding custom functionality
+
+
+## 🎯 Perfect For
+
+- **API Development**: REST and basic GraphQL API creation
+- **Data-Intensive Applications**: Efficient entity management
+- **Content Management**: Basic file upload and handling
+- **Business Applications**: Structured data with relationships
+
+---
+
+*Built with ❤️ using Bun, TypeScript, and PostgreSQL*

package/docs/_sidebar.md

@@ -0,0 +1,23 @@
+- **Getting Started**
+  - [Overview](README.md)
+  - [Installation](getting-started.md)
+  - [Quick Start](getting-started.md#quick-start)
+  - [Configuration](getting-started.md#configuration)
+
+- **Core Concepts**
+  - [Entity System](core-concepts/entity.md)
+  - [Components](core-concepts/components.md)
+  - [ArcheTypes](core-concepts/archetypes.md)
+  - [Services](core-concepts/services.md)
+  - [Query System](core-concepts/query.md)
+  - [Lifecycle Hooks](core-concepts/hooks.md)
+
+- **API Reference**
+  - [Core API](api/core.md)
+  - [Query API](api/query.md)
+  - [Service API](api/service.md)
+  - [Hook API](api/hooks.md)
+  - [Upload API](api/upload.md)
+
+- **Examples & Tutorials**
+  - [Code Examples](examples/code-examples.md)