bunsane 0.1.0 → 0.1.1

package/.github/workflows/deploy-docs.yml

@@ -0,0 +1,57 @@
+name: Deploy Documentation to GitHub Pages
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/deploy-docs.yml'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/deploy-docs.yml'
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '18'
+
+    - name: Install dependencies
+      run: |
+        cd docs
+        npm install -g docsify-cli@latest
+
+    - name: Build documentation
+      run: |
+        cd docs
+        # Generate any dynamic content if needed
+        echo "Building documentation..."
+
+    - name: Deploy to GitHub Pages
+      if: github.ref == 'refs/heads/main'
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs
+
+  validate-links:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Link Checker
+      uses: lycheeverse/lychee-action@v1.8.0
+      with:
+        args: --config docs/.lychee.toml docs/
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 BunSane contributors
+Copyright (c) 2025 Yaaruu
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="./BunSane.jpg" alt="BunSane" width="520" />
+<img src="https://raw.githubusercontent.com/yaaruu/bunsane/refs/heads/main/BunSane.jpg" alt="BunSane" width="520" />
 
 # BunSane — Batteries‑included TypeScript API framework for Bun
 
@@ -20,35 +20,9 @@
 - Pino logging, pretty mode in development
 - Zod-friendly GraphQL error helper
 
-## Install
 
-Requires Bun and PostgreSQL.
+Full documentation visit: [Documentation](https://yaaruu.github.io/bunsane/#/)
 
-```cmd
-bun install @yaaruu/bunsane
-```
-
-Ensure your tsconfig enables decorators in your app:
-
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  }
-}
-```
-
-Full documentation visit: [Documentation](https://example.com)
-
-## Core concepts
-
-### ECS ( Entity Component Services )
-TODO
-
-
-## LICENSE 
-MIT
 
 ---
 

package/TODO.md

@@ -1 +1,8 @@
-// TODO: Add index when component was registered but changed
+// CORE FEATURE
+TODO: Custom Component Table with Direct Column instead of jsonb
+TODO: Add GraphQL type registration for Interface, Enum, etc
+
+// QOL FEATURE
+TODO: Filesystem
+TODO: Field Constraint
+TODO: Add OpenAPI Swagger Spec

package/bun.lock

@@ -4,6 +4,7 @@
     "": {
       "name": "bunsane",
       "dependencies": {
+        "dataloader": "^2.2.2",
         "graphql": "^16.11.0",
         "graphql-yoga": "^5.15.1",
         "pino": "^9.9.0",
@@ -74,6 +75,8 @@
 
     "csstype": ["csstype@3.1.3", "", {}, "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw=="],
 
+    "dataloader": ["dataloader@2.2.3", "", {}, "sha512-y2krtASINtPFS1rSDjacrFgn1dcUuoREVabwlOGOe4SdxenREqwjwjElAdwvbGM7kgZz9a3KVicWR7vcz8rnzA=="],
+
     "dateformat": ["dateformat@4.6.3", "", {}, "sha512-2P0p0pFGzHS5EMnhdxQi7aJN+iMheud0UhG4dlE1DLAlvL8JHjJJTX/CSm4JXwV0Ka5nGk3zC5mcb5bUQUxxMA=="],
 
     "dset": ["dset@3.1.4", "", {}, "sha512-2QF/g9/zTaPDc3BjNcVTGoBbXBgYfMTTceLaYcFJ/W9kggFUkhxD/hMEeuLKbugyef9SqAx8cpgwlIP/jinUTA=="],

package/config/upload.config.ts

@@ -0,0 +1,135 @@
+import type { UploadConfiguration } from "../types/upload.types";
+
+/**
+ * Default Upload Configuration
+ * Contains sensible defaults for the upload system
+ */
+export const DEFAULT_UPLOAD_CONFIG: UploadConfiguration = {
+    maxFileSize: 10 * 1024 * 1024, // 10MB
+    allowedMimeTypes: [
+        // Images
+        "image/jpeg",
+        "image/png", 
+        "image/gif",
+        "image/webp",
+        "image/svg+xml",
+        // Documents
+        "application/pdf",
+        "text/plain",
+        "application/msword",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+    ],
+    allowedExtensions: [
+        // Images
+        ".jpg", ".jpeg", ".png", ".gif", ".webp", ".svg",
+        // Documents  
+        ".pdf", ".txt", ".doc", ".docx"
+    ],
+    validateFileSignature: true,
+    sanitizeFileName: true,
+    preserveOriginalName: false,
+    generateThumbnails: false,
+    uploadPath: "uploads",
+    namingStrategy: "uuid",
+    imageProcessing: {
+        generateThumbnails: false,
+        thumbnailSizes: [
+            { width: 150, height: 150, suffix: "_thumb" },
+            { width: 300, height: 300, suffix: "_medium" },
+            { width: 800, height: 600, suffix: "_large" }
+        ],
+        compress: true,
+        quality: 85,
+        maxDimensions: { width: 2048, height: 2048 }
+    },
+    validation: {
+        scanForMalware: false,
+        strictMimeType: true,
+        customValidators: []
+    }
+};
+
+/**
+ * Image-specific upload configuration
+ */
+export const IMAGE_UPLOAD_CONFIG: Partial<UploadConfiguration> = {
+    maxFileSize: 5 * 1024 * 1024, // 5MB
+    allowedMimeTypes: [
+        "image/jpeg",
+        "image/png",
+        "image/gif", 
+        "image/webp"
+    ],
+    allowedExtensions: [".jpg", ".jpeg", ".png", ".gif", ".webp"],
+    generateThumbnails: true,
+    imageProcessing: {
+        generateThumbnails: true,
+        thumbnailSizes: [
+            { width: 150, height: 150, suffix: "_thumb" },
+            { width: 300, height: 300, suffix: "_medium" }
+        ],
+        compress: true,
+        quality: 85,
+        maxDimensions: { width: 1920, height: 1080 }
+    }
+};
+
+/**
+ * Document upload configuration
+ */
+export const DOCUMENT_UPLOAD_CONFIG: Partial<UploadConfiguration> = {
+    maxFileSize: 25 * 1024 * 1024, // 25MB
+    allowedMimeTypes: [
+        "application/pdf",
+        "text/plain",
+        "application/msword",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.ms-excel",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    ],
+    allowedExtensions: [".pdf", ".txt", ".doc", ".docx", ".xls", ".xlsx"],
+    validateFileSignature: true,
+    generateThumbnails: false,
+    validation: {
+        scanForMalware: true,
+        strictMimeType: true
+    }
+};
+
+/**
+ * Avatar/profile picture configuration
+ */
+export const AVATAR_UPLOAD_CONFIG: Partial<UploadConfiguration> = {
+    maxFileSize: 2 * 1024 * 1024, // 2MB
+    allowedMimeTypes: ["image/jpeg", "image/png", "image/webp"],
+    allowedExtensions: [".jpg", ".jpeg", ".png", ".webp"],
+    generateThumbnails: true,
+    imageProcessing: {
+        generateThumbnails: true,
+        thumbnailSizes: [
+            { width: 50, height: 50, suffix: "_small" },
+            { width: 150, height: 150, suffix: "_medium" },
+            { width: 300, height: 300, suffix: "_large" }
+        ],
+        compress: true,
+        quality: 90,
+        maxDimensions: { width: 800, height: 800 }
+    }
+};
+
+/**
+ * Strict security configuration for public uploads
+ */
+export const SECURE_UPLOAD_CONFIG: Partial<UploadConfiguration> = {
+    maxFileSize: 1 * 1024 * 1024, // 1MB
+    allowedMimeTypes: ["image/jpeg", "image/png"],
+    allowedExtensions: [".jpg", ".jpeg", ".png"],
+    validateFileSignature: true,
+    sanitizeFileName: true,
+    preserveOriginalName: false,
+    validation: {
+        scanForMalware: true,
+        strictMimeType: true,
+        customValidators: []
+    }
+};

package/core/App.ts

@@ -4,9 +4,18 @@ import ComponentRegistry from "core/ComponentRegistry";
 import { logger } from "core/Logger";
 import { createYogaInstance } from "gql";
 import ServiceRegistry from "service/ServiceRegistry";
+import type { Plugin } from "graphql-yoga";
+import * as path from "path";
+import { registerDecoratedHooks } from "core/decorators/EntityHooks";
+import { SchedulerManager } from "core/SchedulerManager";
+import { registerScheduledTasks } from "core/decorators/ScheduledTask";
 
 export default class App {
     private yoga: any;
+    private yogaPlugins: Plugin[] = [];
+    private restEndpoints: Array<{ method: string; path: string; handler: Function; service: any }> = [];
+    private restEndpointMap: Map<string, { method: string; path: string; handler: Function; service: any }> = new Map();
+    private staticAssets: Map<string, string> = new Map();
 
     constructor() {
         this.init();
@@ -32,6 +41,18 @@ export default class App {
                     break;
                 }
                 case ApplicationPhase.COMPONENTS_READY: {
+                    // Automatically register decorated hooks for all services
+                    const services = ServiceRegistry.getServices();
+                    for (const service of services) {
+                        try {
+                            registerDecoratedHooks(service);
+                        } catch (error) {
+                            logger.warn(`Failed to register hooks for service ${service.constructor.name}`);
+                            logger.warn(error);
+                        }
+                    }
+                    logger.info(`Registered hooks for ${services.length} services`);
+                    
                     ApplicationLifecycle.setPhase(ApplicationPhase.SYSTEM_REGISTERING);
                     break;
                 }
@@ -39,10 +60,45 @@ export default class App {
                     try {
                         const schema = ServiceRegistry.getSchema();
                         if (schema) {
-                            this.yoga = createYogaInstance(schema);
+                            this.yoga = createYogaInstance(schema, this.yogaPlugins);
                         } else {
-                            this.yoga = createYogaInstance();
+                            this.yoga = createYogaInstance(undefined, this.yogaPlugins);
                         }
+
+                        // Get all services for processing
+                        const services = ServiceRegistry.getServices();
+
+                        // Initialize Scheduler
+                        const scheduler = SchedulerManager.getInstance();
+
+                        // Register scheduled tasks for all services
+                        for (const service of services) {
+                            try {
+                                registerScheduledTasks(service);
+                            } catch (error) {
+                                logger.warn(`Failed to register scheduled tasks for service ${service.constructor.name}`);
+                                logger.warn(error);
+                            }
+                        }
+                        logger.info(`Registered scheduled tasks for ${services.length} services`);
+
+                        // Collect REST endpoints from all services
+                        for (const service of services) {
+                            const endpoints = (service.constructor as any).httpEndpoints;
+                            if (endpoints) {
+                                for (const endpoint of endpoints) {
+                                    const endpointInfo = {
+                                        method: endpoint.method,
+                                        path: endpoint.path,
+                                        handler: endpoint.handler.bind(service),
+                                        service: service
+                                    };
+                                    this.restEndpoints.push(endpointInfo);
+                                    this.restEndpointMap.set(`${endpoint.method}:${endpoint.path}`, endpointInfo);
+                                }
+                            }
+                        }
+
                         ApplicationLifecycle.setPhase(ApplicationPhase.APPLICATION_READY);
                     } catch (error) {
                         logger.error("Error during SYSTEM_READY phase:");
@@ -71,11 +127,70 @@ export default class App {
         });
     }
 
+    public addYogaPlugin(plugin: Plugin) {
+        this.yogaPlugins.push(plugin);
+    }
+
+    public addStaticAssets(route: string, folder: string) {
+        // Resolve the folder path relative to the current working directory
+        const resolvedFolder = path.resolve(folder);
+        this.staticAssets.set(route, resolvedFolder);
+    }
+
+    private async handleRequest(req: Request): Promise<Response> {
+        const url = new URL(req.url);
+        const method = req.method;
+      
+        // Check for static assets
+        for (const [route, folder] of this.staticAssets) {
+            if (url.pathname.startsWith(route)) {
+                const relativePath = url.pathname.slice(route.length);
+                const filePath = path.join(folder, relativePath);
+                try {
+                    const file = Bun.file(filePath);
+                    if (await file.exists()) {
+                        return new Response(file);
+                    }
+                } catch (error) {
+                    logger.error(`Error serving static file ${filePath}:`, error as any);
+                }
+            }
+        }
+
+        // Lookup REST endpoint using map for O(1) performance
+        const endpointKey = `${method}:${url.pathname}`;
+        const endpoint = this.restEndpointMap.get(endpointKey);
+        if (endpoint) {
+            try {
+                const result = await endpoint.handler(req);
+                if (result instanceof Response) {
+                    return result;
+                } else {
+                    return new Response(JSON.stringify(result), {
+                        headers: { 'Content-Type': 'application/json' }
+                    });
+                }
+            } catch (error) {
+                logger.error(`Error in REST endpoint ${method} ${endpoint.path}`, error as any);
+                return new Response(JSON.stringify({ error: 'Internal server error' }), {
+                    status: 500,
+                    headers: { 'Content-Type': 'application/json' }
+                });
+            }
+        }
+
+        if (this.yoga) {
+            return this.yoga(req);
+        }
+
+        return new Response('Not Found', { status: 404 });
+    }
+
     async start() {
         logger.info("Application Started");
         const server = Bun.serve({
-            fetch: this.yoga
+            fetch: this.handleRequest.bind(this),
         });
-        logger.info(`Server is running on ${new URL(this.yoga.graphqlEndpoint, `http://${server.hostname}:${server.port}`)}`)
+        logger.info(`Server is running on ${new URL(this.yoga?.graphqlEndpoint || '/graphql', `http://${server.hostname}:${server.port}`)}`)
     }
 }

package/core/ArcheType.ts

@@ -0,0 +1,122 @@
+import type { BaseComponent, ComponentDataType } from "./Components";
+import { Entity } from "./Entity";
+
+function compNameToFieldName(compName: string): string {
+    return compName.charAt(0).toLowerCase() + compName.slice(1).replace(/Component$/, '');
+}
+
+/**
+ * ArcheType provides a layer of abstraction for creating entities with predefined sets of components.
+ * This makes entity creation more elegant and reduces code repetition.
+ * 
+ * Example usage:
+ * ```typescript
+ * const UserArcheType = new ArcheType([NameComponent, EmailComponent, PasswordComponent]);
+ *
+ * 
+ * // FROM Request or other source 
+ * const userInput = { name: "John Doe", email: "john@example.com", password: "securepassword" };
+ * const entity = UserArcheType.fill(userInput).createEntity();
+ * await entity.save();
+ * ```
+ */
+
+
+class ArcheType {
+    protected components: Set<{ ctor: new (...args: any[]) => BaseComponent, data: any }> = new Set();
+    protected componentMap: Record<string, typeof BaseComponent> = {}; 
+
+    constructor(components: Array<new (...args: any[]) => BaseComponent>) {
+        for (const ctor of components) {
+            this.componentMap[compNameToFieldName(ctor.name)] = ctor;
+        }
+    }
+   
+    
+    private addComponent<T extends BaseComponent>(ctor: new (...args: any[]) => T, data: ComponentDataType<T>) {
+        this.componentMap[compNameToFieldName(ctor.name)] = ctor;
+        this.components.add({ ctor, data });
+    }
+
+
+    // TODO: Can we make this type-safe?
+    public fill(input: object, strict: boolean = false): this {
+        for (const [key, value] of Object.entries(input)) {
+            if (value !== undefined) {
+                const compCtor = this.componentMap[key];
+                if (compCtor) {
+                    this.addComponent(compCtor, { value });
+                } else {
+                    if (strict) {
+                        throw new Error(`Component for field '${key}' not found in archetype.`);
+                    }
+                }
+            }
+        }
+        for (const [field, ctor] of Object.entries(this.componentMap)) {
+            const alreadyAdded = Array.from(this.components).some(c => c.ctor === ctor);
+            if (!alreadyAdded) {
+                this.addComponent(ctor, {} as any);
+            }
+        }
+        
+        return this;
+    }
+
+    async updateEntity<T>(entity: Entity, updates: Partial<T>) {
+        for (const key of Object.keys(updates)) {
+            if(key === 'id' || key === '_id') continue;
+            const value = updates[key as keyof T];
+            if (value !== undefined) {
+                const compCtor = this.componentMap[key];
+                if (compCtor) {
+                    await entity.set(compCtor, { value });
+                } else {
+                    throw new Error(`Component for field '${key}' not found in archetype.`);
+                }
+            }
+        }
+    }
+
+    /**
+     * Creates a new entity with all the predefined components from this archetype.
+     * @returns A new Entity instance with all archetype components added
+     */
+    public createEntity(): Entity {
+        const entity = Entity.Create();
+        for (const { ctor, data } of this.components) {
+            entity.add(ctor, data);
+        }
+        return entity;
+    }
+
+    /**
+     * Creates a new entity and immediately saves it to the database.
+     * @returns A promise that resolves to the saved Entity
+     */
+    public async createAndSaveEntity(): Promise<Entity> {
+        const entity = this.createEntity();
+        await entity.save();
+        return entity;
+    }
+
+    /**
+     * Unwraps an entity into a plain object containing the component data.
+     * @param entity The entity to unwrap
+     * @param exclude An optional array of field names to exclude from the result (e.g., sensitive data like passwords)
+     * @returns A promise that resolves to an object with component data
+     */
+    public async Unwrap(entity: Entity, exclude: string[] = []): Promise<Record<string, any>> {
+        const result: any = { id: entity.id };
+        for (const [field, ctor] of Object.entries(this.componentMap)) {
+            if (exclude.includes(field)) continue;
+            const comp = await entity.get(ctor as any);
+            if (comp) {
+                result[field] = (comp as any).value;
+            }
+        }
+        return result;
+    }
+}
+
+export default ArcheType;

package/core/BatchLoader.ts

@@ -0,0 +1,100 @@
+import { Entity } from "core/Entity";
+import { BaseComponent } from "core/Components";
+import { timed } from "./Decorators";
+import db from "../database";
+import { sql } from "bun";
+
+// Phase 2A: Memory Pooling for Entity Objects
+class EntityPool {
+    private static instance: EntityPool;
+    private pool: Map<string, Entity[]> = new Map();
+    private maxPoolSize = 1000;
+
+    static getInstance(): EntityPool {
+        if (!EntityPool.instance) {
+            EntityPool.instance = new EntityPool();
+        }
+        return EntityPool.instance;
+    }
+
+    get(entityId: string): Entity | null {
+        const entities = this.pool.get(entityId);
+        if (entities && entities.length > 0) {
+            return entities.pop()!;
+        }
+        return null;
+    }
+
+    put(entity: Entity): void {
+        const entityId = entity.id;
+        let entities = this.pool.get(entityId);
+        if (!entities) {
+            entities = [];
+            this.pool.set(entityId, entities);
+        }
+        if (entities.length < this.maxPoolSize) {
+            entities.push(entity);
+        }
+    }
+
+    clear(): void {
+        this.pool.clear();
+    }
+}
+
+export class BatchLoader {
+    private static entityPool = EntityPool.getInstance();
+
+    @timed("BatchLoader.loadRelatedEntities")
+    static async loadRelatedEntities<C extends BaseComponent & { value: string }>(
+        entities: Entity[],
+        component: new () => C,
+        loader: (ids: string[]) => Promise<Entity[]>
+    ): Promise<Map<string, Entity>> {
+        const ids: string[] = [];
+        for (const entity of entities) {
+            const data = await entity.get(component) as any;
+            if (data?.value) {
+                ids.push(data.value);
+            }
+        }
+        const uniqueIds = [...new Set(ids)];
+        const relatedEntities = await loader(uniqueIds);
+        const map = new Map<string, Entity>();
+        for (const related of relatedEntities) {
+            map.set(related.id, related);
+        }
+        return map;
+    }
+
+    @timed("BatchLoader.loadRelatedEntitiesBatched")
+    static async loadRelatedEntitiesBatched<C extends BaseComponent>(
+        entities: Entity[],
+        component: new () => C,
+        loader: (ids: string[]) => Promise<Entity[]>
+    ): Promise<Map<string, Entity>> {
+        if (entities.length === 0) return new Map();
+
+        const comp = new component();
+        const typeId = comp.getTypeID();
+        const parentIds = entities.map(e => e.id);
+
+        const rows = await db`
+            SELECT c.entity_id, (c.data->>'value') AS related_id
+            FROM components c
+            WHERE c.entity_id IN ${sql(parentIds)}
+              AND c.type_id = ${typeId}
+              AND c.deleted_at IS NULL
+        `;
+
+        const uniqueIds = [...new Set(rows.map((r: any) => r.related_id).filter(Boolean))] as string[];
+        if (uniqueIds.length === 0) return new Map();
+
+        const relatedEntities = await loader(uniqueIds);
+        const map = new Map<string, Entity>();
+        for (const related of relatedEntities) {
+            map.set(related.id, related);
+        }
+        return map;
+    }
+}

package/core/ComponentRegistry.ts

@@ -1,6 +1,6 @@
 import { generateTypeId, type BaseComponent } from "./Components";
 import ApplicationLifecycle, { ApplicationPhase } from "./ApplicationLifecycle";
-import { CreateComponentPartitionTable } from "database/DatabaseHelper";
+import { CreateComponentPartitionTable, UpdateComponentIndexes } from "database/DatabaseHelper";
 import { GetSchema } from "database/DatabaseHelper";
 import { logger as MainLogger } from "./Logger";
 const logger = MainLogger.child({ scope: "ComponentRegistry" });
@@ -94,13 +94,14 @@ class ComponentRegistry {
         return new Promise<boolean>(async resolve => {
             const partitionTableName = `components_${this.sluggifyName(name)}`;
             await this.populateCurrentTables();
+            const instance = new ctor();
+            const indexedProps = instance.indexedProperties();
             if (!this.currentTables.includes(partitionTableName)) {
                 logger.trace(`Partition table ${partitionTableName} does not exist. Creating... name: ${name}, typeId: ${typeid}`);
-                const instance = new ctor();
-                const indexedProps = instance.indexedProperties();
                 await CreateComponentPartitionTable(name, typeid, indexedProps);
                 await this.populateCurrentTables();
             }
+            await UpdateComponentIndexes(partitionTableName, indexedProps);
             this.componentsMap.set(name, typeid);
             this.typeIdToCtor.set(typeid, ctor);
             resolve(true);