bunsane 0.1.4 → 0.2.0

package/core/{ComponentRegistry.ts → components/ComponentRegistry.ts}

@@ -1,11 +1,22 @@
-import { generateTypeId, type BaseComponent } from "./Components";
-import ApplicationLifecycle, { ApplicationPhase } from "./ApplicationLifecycle";
-import { CreateComponentPartitionTable, GenerateTableName, UpdateComponentIndexes } from "database/DatabaseHelper";
-import { GetSchema } from "database/DatabaseHelper";
-import { logger as MainLogger } from "./Logger";
-import { getMetadataStorage } from "./metadata";
-import { registerDecoratedHooks } from "./decorators/EntityHooks";
-import ServiceRegistry from "service/ServiceRegistry";
+import { generateTypeId } from "./Decorators";
+import { type BaseComponent } from "./BaseComponent";
+import ApplicationLifecycle, {
+    ApplicationPhase,
+} from "../ApplicationLifecycle";
+import {
+    CreateComponentPartitionTable,
+    GenerateTableName,
+    UpdateComponentIndexes,
+    AnalyzeAllComponentTables,
+    GetPartitionStrategy,
+} from "../../database/DatabaseHelper";
+import { ensureMultipleJSONBPathIndexes } from "../../database/IndexingStrategy";
+import { GetSchema } from "../../database/DatabaseHelper";
+import { logger as MainLogger } from "../Logger";
+import { getMetadataStorage } from "../metadata";
+import { registerDecoratedHooks } from "../decorators/EntityHooks";
+import ServiceRegistry from "../../service/ServiceRegistry";
+import { preparedStatementCache } from "../../database/PreparedStatementCache";
 const logger = MainLogger.child({ scope: "ComponentRegistry" });
 
 type ComponentConstructor = new () => BaseComponent;
@@ -17,15 +28,14 @@ class ComponentRegistry {
     private componentQueue = new Map<string, ComponentConstructor>();
     private currentTables: string[] = [];
     private componentsMap = new Map<string, string>();
+    private typeIdToName = new Map<string, string>();
     private typeIdToCtor = new Map<string, ComponentConstructor>();
     private instantRegister: boolean = false;
     private readinessPromises = new Map<string, Promise<void>>();
     private readinessResolvers = new Map<string, () => void>();
     private componentsRegistered: boolean = false;
 
-    constructor() {
-        
-    }
+    constructor() {}
 
     public init() {
         // Listener removed to make component registration sequential
@@ -47,27 +57,27 @@ class ComponentRegistry {
         }
     }
 
-    define(
-        name: string,
-        ctor: ComponentConstructor
-    ) {
-        if(!this.instantRegister) {
-            if(!this.componentQueue.has(name)) {
+    define(name: string, ctor: ComponentConstructor) {
+        if (!this.instantRegister) {
+            if (!this.componentQueue.has(name)) {
                 this.componentQueue.set(name, ctor);
-                this.readinessPromises.set(name, new Promise<void>(resolve => {
-                    this.readinessResolvers.set(name, resolve);
-                }));
+                this.readinessPromises.set(
+                    name,
+                    new Promise<void>((resolve) => {
+                        this.readinessResolvers.set(name, resolve);
+                    })
+                );
                 return;
             }
         }
-        if(this.instantRegister) {
-            if(this.componentsMap.has(name)) {
+        if (this.instantRegister) {
+            if (this.componentsMap.has(name)) {
                 logger.trace(`Component already registered: ${name}`);
                 return;
             }
             this.register(name, generateTypeId(name), ctor).then(() => {
                 const resolve = this.readinessResolvers.get(name);
-                if(resolve) resolve();
+                if (resolve) resolve();
             });
         }
     }
@@ -84,16 +94,16 @@ class ComponentRegistry {
         if (this.isComponentReady(name)) {
             return Promise.resolve();
         }
-        
+
         // Ensure components are registered before trying to find the component
         await this.ensureComponentsRegistered();
-        
+
         if (this.isComponentReady(name)) {
             return Promise.resolve();
         }
-        
+
         const storage = getMetadataStorage();
-        const component = storage.components.find(c => c.name === name);
+        const component = storage.components.find((c) => c.name === name);
         if (component) {
             // Component exists in metadata but not registered yet, register it
             return this.registerComponentFromMetadata(component);
@@ -114,6 +124,27 @@ class ComponentRegistry {
         return this.componentsMap.get(name);
     }
 
+    getComponentName(typeId: string): string | undefined {
+        return this.typeIdToName.get(typeId);
+    }
+
+    /**
+     * Get component constructor by component name
+     * @param name Component class name
+     * @returns Component constructor or undefined
+     */
+    getConstructorByName(name: string): ComponentConstructor | undefined {
+        const typeId = this.componentsMap.get(name);
+        if (!typeId) return undefined;
+        return this.typeIdToCtor.get(typeId);
+    }
+
+    getPartitionTableName(typeId: string): string | null {
+        const name = this.typeIdToName.get(typeId);
+        if (!name) return null;
+        return GenerateTableName(name);
+    }
+
     getConstructor(typeId: string) {
         return this.typeIdToCtor.get(typeId);
     }
@@ -137,48 +168,54 @@ class ComponentRegistry {
         if (this.componentsRegistered) {
             return; // Already registered
         }
-        
+
         logger.trace("Registering Components...");
         ApplicationLifecycle.setPhase(ApplicationPhase.COMPONENTS_REGISTERING);
-        
+
         await this.populateCurrentTables();
         const storage = getMetadataStorage();
-        const promises = storage.components.map(async metadata => {
+        const promises = storage.components.map(async (metadata) => {
             const { name, target: ctor, typeId } = metadata;
-            if(this.componentsMap.has(name)) {
+            if (this.componentsMap.has(name)) {
                 logger.trace(`Component already registered: ${name}`);
                 return;
             }
-            this.readinessPromises.set(name, new Promise<void>(resolve => {
-                this.readinessResolvers.set(name, resolve);
-            }));
+            this.readinessPromises.set(
+                name,
+                new Promise<void>((resolve) => {
+                    this.readinessResolvers.set(name, resolve);
+                })
+            );
             await this.register(name, typeId, ctor as ComponentConstructor);
             const resolve = this.readinessResolvers.get(name);
-            if(resolve) resolve();
+            if (resolve) resolve();
         });
         await Promise.all(promises);
         this.componentsRegistered = true;
-        
+
         // Handle component-related setup that was previously in App.init()
         await this.setupComponentFeatures();
-        
+
         ApplicationLifecycle.setPhase(ApplicationPhase.COMPONENTS_READY);
     }
 
     register(name: string, typeid: string, ctor: ComponentConstructor) {
-        return new Promise<boolean>(async resolve => {
+        return new Promise<boolean>(async (resolve) => {
             const partitionTableName = GenerateTableName(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}`);
+                logger.trace(
+                    `Partition table ${partitionTableName} does not exist. Creating... name: ${name}, typeId: ${typeid}`
+                );
                 // await CreateComponentPartitionTable(name, typeid, indexedProps); // TODO: OLD Logic with indexedProps, remove if not needed
                 await CreateComponentPartitionTable(name, typeid);
                 // await this.populateCurrentTables();
             }
             // await UpdateComponentIndexes(partitionTableName, indexedProps); // TODO: OLD Logic with indexedProps, remove if not needed
             this.componentsMap.set(name, typeid);
+            this.typeIdToName.set(typeid, name);
             this.typeIdToCtor.set(typeid, ctor);
             resolve(true);
         });
@@ -189,9 +226,12 @@ class ComponentRegistry {
         if (this.componentsMap.has(name)) {
             return; // Already registered
         }
-        this.readinessPromises.set(name, new Promise<void>(resolve => {
-            this.readinessResolvers.set(name, resolve);
-        }));
+        this.readinessPromises.set(
+            name,
+            new Promise<void>((resolve) => {
+                this.readinessResolvers.set(name, resolve);
+            })
+        );
         await this.register(name, typeId, ctor as ComponentConstructor);
         const resolve = this.readinessResolvers.get(name);
         if (resolve) resolve();
@@ -200,21 +240,23 @@ class ComponentRegistry {
     private async registerComponentDynamically(name: string): Promise<void> {
         // Try to find the component in global metadata storage
         const storage = getMetadataStorage();
-        const component = storage.components.find(c => c.name === name);
+        const component = storage.components.find((c) => c.name === name);
         if (component) {
             return this.registerComponentFromMetadata(component);
         }
 
         // If still not found, this is an error - component was never decorated
-        throw new Error(`Component ${name} not found in metadata storage. Make sure it's decorated with @Component`);
+        throw new Error(
+            `Component ${name} not found in metadata storage. Make sure it's decorated with @Component`
+        );
     }
 
     getComponents() {
         // returns array of { name, ctor }
-        const components: { name: string, ctor: ComponentConstructor }[] = [];
+        const components: { name: string; ctor: ComponentConstructor }[] = [];
         for (const [name, typeid] of this.componentsMap) {
             const ctor = this.typeIdToCtor.get(typeid);
-            if(ctor) {
+            if (ctor) {
                 components.push({ name, ctor });
             }
         }
@@ -230,16 +272,63 @@ class ComponentRegistry {
         }
     }
 
+    private getIndexedFieldsForComponent(componentName: string) {
+        const storage = getMetadataStorage();
+        const componentId = storage.getComponentId(componentName);
+        return storage.getIndexedFields(componentId);
+    }
+
     private async setupComponentFeatures(): Promise<void> {
         const components = this.getComponents();
-        
+
+        // Invalidate prepared statement cache when component schemas change
+        preparedStatementCache.clear();
+        logger.trace(
+            "Cleared prepared statement cache due to component schema changes"
+        );
+
+        // Check partitioning strategy for index creation
+        const partitionStrategy = await GetPartitionStrategy();
+
         // Update component indexes for components that have indexed properties
-        for(const {name, ctor} of components) {
+        // NOTE: Index operations are serialized to prevent deadlocks with ANALYZE
+        for (const { name, ctor } of components) {
             const instance = new ctor();
-            if(instance.indexedProperties().length > 0) {
-                const table_name = GenerateTableName(name);
-                UpdateComponentIndexes(table_name, instance.indexedProperties());
-                logger.trace(`Updated indexes for component: ${name}`);
+            const table_name = GenerateTableName(name);
+
+            // Handle legacy @CompData(indexed: true) properties
+            if (instance.indexedProperties().length > 0) {
+                // For HASH partitioning, redirect index operations to parent table
+                const indexTableName =
+                    partitionStrategy === "hash" ? "components" : table_name;
+                await UpdateComponentIndexes(
+                    indexTableName,
+                    instance.indexedProperties()
+                );
+                logger.trace(
+                    `Updated legacy indexes for component: ${name} on table: ${indexTableName}`
+                );
+            }
+
+            // Handle new @IndexedField decorators
+            const indexedFields = this.getIndexedFieldsForComponent(name);
+            if (indexedFields.length > 0) {
+                // For HASH partitioning, create indexes on parent table
+                const indexTableName =
+                    partitionStrategy === "hash" ? "components" : table_name;
+                const indexDefinitions = indexedFields.map((field) => ({
+                    tableName: indexTableName,
+                    field: field.propertyKey,
+                    indexType: field.indexType,
+                    isDateField: field.isDateField,
+                }));
+                await ensureMultipleJSONBPathIndexes(
+                    indexTableName,
+                    indexDefinitions
+                );
+                logger.trace(
+                    `Created specialized indexes for component: ${name} on table: ${indexTableName}`
+                );
             }
         }
 
@@ -249,12 +338,17 @@ class ComponentRegistry {
             try {
                 registerDecoratedHooks(service);
             } catch (error) {
-                logger.warn(`Failed to register hooks for service ${service.constructor.name}`);
+                logger.warn(
+                    `Failed to register hooks for service ${service.constructor.name}`
+                );
                 logger.warn(error);
             }
         }
         logger.info(`Registered hooks for ${services.length} services`);
+
+        // Run ANALYZE on all component tables to update query planner statistics
+        await AnalyzeAllComponentTables();
     }
 }
 
-export default ComponentRegistry.instance;
+export default ComponentRegistry.instance;

package/core/components/Decorators.ts

@@ -0,0 +1,88 @@
+import { createHash } from 'crypto';
+import "reflect-metadata";
+import { logger as MainLogger } from "../Logger";
+import ComponentRegistry from "./ComponentRegistry";
+import { type ComponentDataType } from './Interfaces';
+import { uuidv7 } from '../../utils/uuid';
+import { getMetadataStorage } from '../metadata';
+const logger = MainLogger.child({ scope: "Components" });
+import BaseComponent from './BaseComponent';
+
+export function generateTypeId(name: string): string {
+  return createHash('sha256').update(name).digest('hex');
+}
+
+const primitiveTypes = [String, Number, Boolean, Symbol, BigInt, Date];
+
+export function CompData(options?: { indexed?: boolean; nullable?: boolean; arrayOf?: any }) {
+    return (target: any, propertyKey: string) => {
+        const storage = getMetadataStorage();
+        const typeId = storage.getComponentId(target.constructor.name);
+        const propType = Reflect.getMetadata("design:type", target, propertyKey);
+        let isEnum = !!(Reflect.getMetadata("isEnum", propType));
+        // console.log(`Property ${propertyKey} type:`, propType?.name);
+        // console.log(`Is Enum:`, isEnum);
+        let enumValues: string[] | undefined = undefined;
+        let enumKeys: string[] | undefined = undefined;
+        if(isEnum) {
+            const metaEnumValues = Reflect.getMetadata("__enumValues", propType);
+            const metaEnumKeys = Reflect.getMetadata("__enumKeys", propType);
+            
+            if (metaEnumValues && metaEnumKeys) {
+                enumValues = metaEnumValues;
+                enumKeys = metaEnumKeys;
+            } else {
+                const staticKeys = Object.getOwnPropertyNames(propType).filter(key => 
+                    key !== 'prototype' && 
+                    key !== 'length' && 
+                    key !== 'name' &&
+                    key !== 'isEnum' &&
+                    key !== '__enumValues' &&
+                    key !== '__enumKeys' &&
+                    typeof propType[key] !== 'function' &&
+                    typeof propType[key] !== 'boolean'
+                );
+                if (staticKeys.length > 0) {
+                    enumValues = staticKeys.map(key => propType[key]);
+                    enumKeys = staticKeys;
+                } else {
+                    // Fallback for numeric enums
+                    enumValues = Object.keys(propType).filter(key => !isNaN(Number(key))).map(key => propType[key]);
+                }
+            }
+        }
+        storage.collectComponentPropertyMetadata({
+            component_id: typeId,
+            propertyKey: propertyKey,
+            propertyType: propType,
+            indexed: options?.indexed ?? false,
+            isPrimitive: primitiveTypes.includes(propType),
+            isEnum: isEnum,
+            enumValues: enumValues,
+            enumKeys: enumKeys,
+            isOptional: options?.nullable ?? false,
+            arrayOf: options?.arrayOf,
+        })
+        // Reflect.metadata("compData", { isData: true, indexed: options?.indexed ?? false })(target, propertyKey);
+    };
+}
+
+export function Component<T extends new () => BaseComponent>(target: T): T {
+    const storage = getMetadataStorage();
+    const typeId = storage.getComponentId(target.name);
+    const properties = storage.getComponentProperties(typeId);
+    // console.log(`Component decorator applied to ${target.name} with typeId ${typeId} and properties:`, properties);
+    storage.collectComponentMetadata({
+        name: target.name,
+        typeId: typeId,
+        target: target,
+    });
+    // ComponentRegistry.define(target.name, target);
+    return target;
+}
+
+
+
+export type ComponentGetter<T extends BaseComponent> = Pick<T, "properties" | "id"> & {
+    data(): ComponentDataType<T>;
+};

package/core/components/Interfaces.ts

@@ -0,0 +1,7 @@
+import type BaseComponent from './BaseComponent';
+export type ComponentDataType<T extends BaseComponent> = {
+    [K in keyof T as T[K] extends Function ? never : 
+                    K extends `_${string}` ? never : 
+                    K extends 'id' | 'getTypeID' | 'properties' | 'data' | 'save' | 'insert' | 'update' ? never : 
+                    K]: T[K];
+};

package/core/components/index.ts

@@ -0,0 +1,5 @@
+import ComponentRegistry from "./ComponentRegistry";
+export { CompData, Component, type ComponentGetter} from "./Decorators";
+export { BaseComponent } from "./BaseComponent";
+export {type ComponentDataType} from "./Interfaces";
+export {ComponentRegistry};

package/core/decorators/EntityHooks.ts

@@ -183,8 +183,5 @@ export function registerDecoratedHooks(serviceInstance: any): void {
  * @param serviceInstance The service instance to unregister hooks for
  */
 export function unregisterDecoratedHooks(serviceInstance: any): void {
-    // Note: This is a simplified implementation
-    // In a production system, you'd want to track hook IDs during registration
-    // and use them for targeted removal here
     console.warn('unregisterDecoratedHooks is not fully implemented. Use EntityHookManager.removeHook() for individual hook removal.');
 }

package/core/decorators/IndexedField.ts

@@ -0,0 +1,26 @@
+import { getMetadataStorage } from '../metadata';
+
+/**
+ * Decorator to mark component fields that should have dedicated database indexes
+ * This is used for frequently filtered fields to improve query performance
+ *
+ * @param indexType The type of index to create:
+ *   - 'gin': GIN index for JSONB containment queries (default)
+ *   - 'btree': BTREE index for equality and text comparisons
+ *   - 'hash': HASH index for exact equality lookups
+ *   - 'numeric': BTREE index with numeric cast for range queries (>, <, BETWEEN)
+ * @param isDateField Whether this field contains date values (affects BTREE index casting)
+ */
+export function IndexedField(indexType: 'gin' | 'btree' | 'hash' | 'numeric' = 'gin', isDateField: boolean = false) {
+    return function(target: any, propertyKey: string) {
+        const storage = getMetadataStorage();
+        const componentId = storage.getComponentId(target.constructor.name);
+
+        storage.collectIndexedFieldMetadata({
+            componentId,
+            propertyKey,
+            indexType,
+            isDateField
+        });
+    };
+}

package/core/decorators/ScheduledTask.ts

@@ -5,53 +5,6 @@ import { logger } from "../Logger";
 
 const loggerInstance = logger.child({ scope: "ScheduledTaskDecorator" });
 
-/**
- * Decorator for registering scheduled tasks
- * @param options Task configuration options including interval and component target
- */
-export function ScheduledTask(
-    options: ScheduledTaskOptions & { 
-        interval: ScheduleInterval; 
-        componentTarget?: new (...args: any[]) => any 
-    }
-) {
-    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
-        const originalMethod = descriptor.value;
-
-        // Generate task ID if not provided
-        const taskId = options.id || `${target.constructor.name}.${propertyKey}`;
-
-        // Store task info for later registration
-        if (!target.constructor.__scheduledTasks) {
-            target.constructor.__scheduledTasks = [];
-        }
-
-        const taskInfo = {
-            id: taskId,
-            name: options.name || `${target.constructor.name}.${propertyKey}`,
-            componentTarget: options.componentTarget, // Legacy support
-            interval: options.interval,
-            options: {
-                runOnStart: options.runOnStart ?? false,
-                timeout: options.timeout ?? 30000,
-                enableLogging: options.enableLogging ?? true,
-                ...options
-            },
-            service: null, // Will be set when service is instantiated
-            methodName: propertyKey,
-            nextExecution: new Date(),
-            executionCount: 0,
-            isRunning: false,
-            enabled: true
-        };
-
-        target.constructor.__scheduledTasks.push(taskInfo);
-
-        // Return the original descriptor to maintain method functionality
-        return descriptor;
-    };
-}
-
 /**
  * Function to manually register decorated tasks for a service instance
  * This is useful when services are instantiated outside the normal decorator flow

package/core/events/EntityLifecycleEvents.ts

@@ -1,5 +1,5 @@
 import type { Entity } from "../Entity";
-import type { BaseComponent } from "../Components";
+import type { BaseComponent } from "../components";
 
 /**
  * Base class for all entity lifecycle events

package/core/health.ts

@@ -0,0 +1,112 @@
+import db from "../database";
+import { CacheManager } from "./cache/CacheManager";
+
+export interface CheckResult {
+    status: string;
+    latency_ms: number;
+}
+
+export interface HealthResponse {
+    status: "ok" | "degraded" | "unavailable";
+    timestamp: string;
+    uptime: number;
+    checks: {
+        database: CheckResult;
+        cache: CheckResult;
+    };
+}
+
+export interface HealthResult {
+    result: HealthResponse;
+    httpStatus: number;
+}
+
+export interface HealthDeps {
+    pingDb: () => Promise<boolean>;
+    pingCache: () => Promise<boolean>;
+}
+
+const defaultDeps: HealthDeps = {
+    pingDb: async () => {
+        await db`SELECT 1`;
+        return true;
+    },
+    pingCache: () => CacheManager.getInstance().ping(),
+};
+
+async function checkDatabase(pingDb: () => Promise<boolean>): Promise<CheckResult> {
+    const start = performance.now();
+    try {
+        await pingDb();
+        return { status: "up", latency_ms: Math.round(performance.now() - start) };
+    } catch {
+        return { status: "down", latency_ms: Math.round(performance.now() - start) };
+    }
+}
+
+async function checkCache(pingCache: () => Promise<boolean>): Promise<CheckResult> {
+    const start = performance.now();
+    try {
+        const ok = await pingCache();
+        return { status: ok ? "up" : "down", latency_ms: Math.round(performance.now() - start) };
+    } catch {
+        return { status: "down", latency_ms: Math.round(performance.now() - start) };
+    }
+}
+
+export async function deepHealthCheck(deps: HealthDeps = defaultDeps): Promise<HealthResult> {
+    const [database, cache] = await Promise.all([
+        checkDatabase(deps.pingDb),
+        checkCache(deps.pingCache),
+    ]);
+
+    const dbUp = database.status === "up";
+    const cacheUp = cache.status === "up";
+
+    let status: HealthResponse["status"];
+    let httpStatus: number;
+
+    if (dbUp && cacheUp) {
+        status = "ok";
+        httpStatus = 200;
+    } else if (dbUp && !cacheUp) {
+        status = "degraded";
+        httpStatus = 200;
+    } else {
+        status = "unavailable";
+        httpStatus = 503;
+    }
+
+    return {
+        result: {
+            status,
+            timestamp: new Date().toISOString(),
+            uptime: process.uptime(),
+            checks: { database, cache },
+        },
+        httpStatus,
+    };
+}
+
+export async function readinessCheck(
+    isReady: boolean,
+    isShuttingDown: boolean,
+    deps: HealthDeps = defaultDeps,
+): Promise<HealthResult> {
+    if (!isReady || isShuttingDown) {
+        return {
+            result: {
+                status: "unavailable",
+                timestamp: new Date().toISOString(),
+                uptime: process.uptime(),
+                checks: {
+                    database: { status: "unknown", latency_ms: 0 },
+                    cache: { status: "unknown", latency_ms: 0 },
+                },
+            },
+            httpStatus: 503,
+        };
+    }
+
+    return deepHealthCheck(deps);
+}

package/core/metadata/definitions/ArcheType.ts

@@ -2,8 +2,22 @@ export interface ArcheTypeMetadata {
     name: string;
     target: Function;
     typeId: string;
+    functions?: ArcheTypeFunctionMetadata[];
+}
+
+export interface ArcheTypeFunctionMetadata {
+    propertyKey: string;
+    options?: { 
+        returnType?: string;
+        args?: Array<{ 
+            name: string; 
+            type: any; 
+            nullable?: boolean;
+        }>;
+    };
 }
 
 export interface ArcheTypeFieldOptions {
     nullable?: boolean;
+    filterable?: boolean;
 }