@engjts/nexus 0.1.0

package/src/core/router/index.ts

@@ -0,0 +1,182 @@
+/**
+ * Router implementation with schema validation
+ */
+
+import { RadixTree } from './radix-tree';
+import {
+    HTTPMethod,
+    Handler,
+    Middleware,
+    RouteConfig,
+    RouteMatch,
+    SchemaConfig,
+    RouteMeta,
+    Context
+} from '../types';
+
+/**
+ * Route with validation schema and metadata
+ */
+interface RouteEntry {
+    handler: Handler;
+    middlewares: Middleware[];
+    schema?: SchemaConfig;
+    meta?: RouteMeta;
+}
+
+/**
+ * Router class
+ */
+export class Router {
+    private trees: Map<HTTPMethod, RadixTree> = new Map();
+    private routes: Array<{ method: HTTPMethod; path: string; config: RouteEntry }> = [];
+
+    constructor() {
+        // Initialize trees for each HTTP method
+        const methods: HTTPMethod[] = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
+        for (const method of methods) {
+            this.trees.set(method, new RadixTree());
+        }
+    }
+
+    /**
+     * Register a route
+     */
+    addRoute(config: RouteConfig): void {
+        const { method, path, handler, middlewares = [], schema, meta } = config;
+
+        const tree = this.trees.get(method);
+        if (!tree) {
+            throw new Error(`Unsupported HTTP method: ${method}`);
+        }
+
+        // Wrap handler with schema validation if provided
+        const wrappedHandler = schema ? this.wrapWithValidation(handler, schema) : handler;
+
+        tree.insert(path, wrappedHandler, middlewares);
+
+        // Store for introspection (including schema and meta for documentation)
+        this.routes.push({
+            method,
+            path,
+            config: { handler: wrappedHandler, middlewares, schema, meta }
+        });
+    }
+
+    /**
+     * Find a matching route
+     */
+    match(method: string, path: string): RouteMatch | null {
+        const tree = this.trees.get(method as HTTPMethod);
+        if (!tree) {
+            return null;
+        }
+
+        const result = tree.search(path);
+        if (!result) {
+            return null;
+        }
+
+        return {
+            handler: result.handler,
+            params: result.params,
+            middlewares: result.middlewares,
+            schema: undefined // Schema already applied in wrapped handler
+        };
+    }
+
+    /**
+     * Get all registered routes with full metadata
+     */
+    getRoutes(): Array<{ method: string; path: string; schema?: SchemaConfig; meta?: RouteMeta }> {
+        return this.routes.map(r => ({ 
+            method: r.method, 
+            path: r.path,
+            schema: r.config.schema,
+            meta: r.config.meta
+        }));
+    }
+
+    /**
+     * Convenience methods for HTTP verbs
+     */
+    get(path: string, handler: Handler, options?: Partial<RouteConfig>): void {
+        this.addRoute({ method: 'GET', path, handler, ...options });
+    }
+
+    post(path: string, handler: Handler, options?: Partial<RouteConfig>): void {
+        this.addRoute({ method: 'POST', path, handler, ...options });
+    }
+
+    put(path: string, handler: Handler, options?: Partial<RouteConfig>): void {
+        this.addRoute({ method: 'PUT', path, handler, ...options });
+    }
+
+    delete(path: string, handler: Handler, options?: Partial<RouteConfig>): void {
+        this.addRoute({ method: 'DELETE', path, handler, ...options });
+    }
+
+    patch(path: string, handler: Handler, options?: Partial<RouteConfig>): void {
+        this.addRoute({ method: 'PATCH', path, handler, ...options });
+    }
+
+    /**
+     * Wrap handler with schema validation
+     */
+    private wrapWithValidation(handler: Handler, schema: SchemaConfig): Handler {
+        return async (ctx: Context) => {
+            try {
+                // Validate params
+                if (schema.params) {
+                    ctx.params = await schema.params.parseAsync(ctx.params);
+                }
+
+                // Validate query
+                if (schema.query) {
+                    ctx.query = await schema.query.parseAsync(ctx.query);
+                }
+
+                // Validate body
+                if (schema.body) {
+                    ctx.body = await schema.body.parseAsync(ctx.body);
+                }
+
+                // Validate headers
+                if (schema.headers) {
+                    ctx.headers = await schema.headers.parseAsync(ctx.headers);
+                }
+
+                // Call original handler with validated data
+                return handler(ctx, {});
+            } catch (error: any) {
+                // Zod validation error
+                if (error.name === 'ZodError') {
+                    // Use custom error handler if provided
+                    if (schema.onValidationError) {
+                        const customResponse = schema.onValidationError(error.errors, ctx);
+                        // If it's already a Response object, return it
+                        if (customResponse?.statusCode) {
+                            return customResponse;
+                        }
+                        // Otherwise wrap it as JSON response
+                        return ctx.json(customResponse, 400);
+                    }
+                    
+                    // Default error response - extract first error message
+                    const firstError = error.errors[0];
+                    const message = firstError?.message || 'Validation failed';
+                    
+                    return ctx.json({
+                        success: false,
+                        message
+                    }, 400);
+                }
+                throw error;
+            }
+        };
+    }
+}
+
+// Re-export file router
+export { FileRouter, createFileRouter, useFileRoutes } from './file-router';
+export type { FileRouterOptions, FileRouteClass, RouteModule } from './file-router';

package/src/core/router/radix-tree.ts

@@ -0,0 +1,226 @@
+/**
+ * Radix Tree implementation for efficient routing
+ * Provides O(log n) route lookup performance
+ */
+
+import { Handler, Middleware } from '../types';
+
+/**
+ * Node in the radix tree
+ */
+export class RadixNode {
+    // The path segment this node represents
+    segment: string;
+
+    // Full path for this node (used for debugging)
+    fullPath: string;
+
+    // Handler if this is a terminal node
+    handler: Handler | null = null;
+
+    // Middleware for this route
+    middlewares: Middleware[] = [];
+
+    // Child nodes
+    children: RadixNode[] = [];
+
+    // Pattern type: 'static', 'param', or 'wildcard'
+    type: 'static' | 'param' | 'wildcard' = 'static';
+
+    // Parameter name for param nodes
+    paramName?: string;
+
+    constructor(segment: string, fullPath: string) {
+        this.segment = segment;
+        this.fullPath = fullPath;
+
+        // Detect node type
+        if (segment.startsWith(':')) {
+            this.type = 'param';
+            this.paramName = segment.slice(1);
+        } else if (segment === '*' || segment.startsWith('*')) {
+            this.type = 'wildcard';
+            this.paramName = segment.length > 1 ? segment.slice(1) : 'wildcard';
+        }
+    }
+
+    /**
+     * Add a child node
+     */
+    addChild(node: RadixNode): void {
+        // Insert maintaining order: static > param > wildcard
+        const priority = this.getTypePriority(node.type);
+        let inserted = false;
+
+        for (let i = 0; i < this.children.length; i++) {
+            const childPriority = this.getTypePriority(this.children[i].type);
+            if (priority < childPriority) {
+                this.children.splice(i, 0, node);
+                inserted = true;
+                break;
+            }
+        }
+
+        if (!inserted) {
+            this.children.push(node);
+        }
+    }
+
+    /**
+     * Find a child by segment
+     */
+    findChild(segment: string): RadixNode | null {
+        for (const child of this.children) {
+            if (child.segment === segment) {
+                return child;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Get type priority for ordering (lower = higher priority)
+     */
+    private getTypePriority(type: 'static' | 'param' | 'wildcard'): number {
+        switch (type) {
+            case 'static': return 0;
+            case 'param': return 1;
+            case 'wildcard': return 2;
+        }
+    }
+}
+
+/**
+ * Radix tree for route storage and matching
+ */
+export class RadixTree {
+    private root: RadixNode;
+
+    constructor() {
+        this.root = new RadixNode('', '/');
+    }
+
+    /**
+     * Insert a route into the tree
+     */
+    insert(path: string, handler: Handler, middlewares: Middleware[] = []): void {
+        const segments = this.splitPath(path);
+        let current = this.root;
+
+        for (let i = 0; i < segments.length; i++) {
+            const segment = segments[i];
+            let child = current.findChild(segment);
+
+            if (!child) {
+                const fullPath = '/' + segments.slice(0, i + 1).join('/');
+                child = new RadixNode(segment, fullPath);
+                current.addChild(child);
+            }
+
+            current = child;
+        }
+
+        // Set handler and middleware at terminal node
+        current.handler = handler;
+        current.middlewares = middlewares;
+    }
+
+    /**
+     * Search for a route match
+     */
+    search(path: string): { handler: Handler; params: Record<string, string>; middlewares: Middleware[] } | null {
+        const segments = this.splitPath(path);
+        const params: Record<string, string> = {};
+
+        const result = this.searchNode(this.root, segments, 0, params);
+
+        if (result) {
+            return {
+                handler: result.handler!,
+                params,
+                middlewares: result.middlewares
+            };
+        }
+
+        return null;
+    }
+
+    /**
+     * Recursively search nodes
+     */
+    private searchNode(
+        node: RadixNode,
+        segments: string[],
+        index: number,
+        params: Record<string, string>
+    ): RadixNode | null {
+        // Reached end of path
+        if (index === segments.length) {
+            return node.handler ? node : null;
+        }
+
+        const segment = segments[index];
+
+        // Try children in priority order
+        for (const child of node.children) {
+            if (child.type === 'static') {
+                // Exact match required
+                if (child.segment === segment) {
+                    const result = this.searchNode(child, segments, index + 1, params);
+                    if (result) return result;
+                }
+            } else if (child.type === 'param') {
+                // Parameter match - capture value
+                const oldValue = params[child.paramName!];
+                params[child.paramName!] = segment;
+
+                const result = this.searchNode(child, segments, index + 1, params);
+                if (result) return result;
+
+                // Backtrack
+                if (oldValue === undefined) {
+                    delete params[child.paramName!];
+                } else {
+                    params[child.paramName!] = oldValue;
+                }
+            } else if (child.type === 'wildcard') {
+                // Wildcard match - capture remaining path
+                params[child.paramName!] = segments.slice(index).join('/');
+                return child;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Split path into segments
+     */
+    private splitPath(path: string): string[] {
+        // Remove leading/trailing slashes and split
+        const normalized = path.replace(/^\/+|\/+$/g, '');
+        return normalized ? normalized.split('/') : [];
+    }
+
+    /**
+     * Get all routes (for debugging/introspection)
+     */
+    getAllRoutes(): Array<{ path: string; hasHandler: boolean }> {
+        const routes: Array<{ path: string; hasHandler: boolean }> = [];
+        this.collectRoutes(this.root, routes);
+        return routes;
+    }
+
+    /**
+     * Recursively collect all routes
+     */
+    private collectRoutes(node: RadixNode, routes: Array<{ path: string; hasHandler: boolean }>): void {
+        if (node.handler) {
+            routes.push({ path: node.fullPath, hasHandler: true });
+        }
+
+        for (const child of node.children) {
+            this.collectRoutes(child, routes);
+        }
+    }
+}

package/src/core/store/index.ts

@@ -0,0 +1,30 @@
+/**
+ * ContextStore System
+ * State management inspired by Flutter's Provider pattern
+ * 
+ * Two types of stores:
+ * - ContextStore: Global singleton, persists across all requests
+ * - RequestStore: Per-request scoped, disposed after response
+ */
+
+// Core store classes
+export { ContextStore } from './types';
+export { RequestStore } from './request-store';
+
+// Types
+export type { 
+    StoreListener, 
+    DisposeCallback, 
+    StoreConstructor, 
+    StateOf, 
+    StoreOptions 
+} from './types';
+
+export type { 
+    RequestStoreConstructor, 
+    RequestStateOf 
+} from './request-store';
+
+// Registries
+export { StoreRegistry, createStoreRegistry } from './registry';
+export { RequestStoreRegistry } from './request-store';

package/src/core/store/registry.ts

@@ -0,0 +1,178 @@
+/**
+ * StoreRegistry - Global store container
+ * Manages all ContextStore instances at application level
+ */
+
+import { ContextStore, StoreConstructor, StoreRegistryOptions } from './types';
+
+/**
+ * StoreRegistry manages all stores in the application
+ * Ensures singleton instances and handles lifecycle
+ */
+export class StoreRegistry {
+    private stores: Map<StoreConstructor<any>, ContextStore<any>> = new Map();
+    private options: StoreRegistryOptions;
+
+    constructor(options: StoreRegistryOptions = {}) {
+        this.options = options;
+    }
+
+    /**
+     * Register a store class
+     * Creates instance immediately
+     * 
+     * @param StoreClass - Store constructor class
+     * @returns The created store instance
+     */
+    register<T extends ContextStore<any>>(StoreClass: StoreConstructor<T>): T {
+        if (this.stores.has(StoreClass)) {
+            if (this.options.debug) {
+                console.log(`[StoreRegistry] Store ${StoreClass.name} already registered`);
+            }
+            return this.stores.get(StoreClass) as T;
+        }
+
+        const instance = new StoreClass({ debug: this.options.debug });
+        this.stores.set(StoreClass, instance);
+
+        if (this.options.debug) {
+            console.log(`[StoreRegistry] Registered store: ${StoreClass.name}`);
+        }
+
+        // Call onInit if defined
+        const initResult = instance.onInit();
+        if (initResult instanceof Promise) {
+            initResult.catch(err => {
+                console.error(`[StoreRegistry] Error in ${StoreClass.name}.onInit():`, err);
+            });
+        }
+
+        return instance;
+    }
+
+    /**
+     * Register multiple stores at once
+     * 
+     * @param storeClasses - Array of store constructor classes
+     */
+    registerAll(storeClasses: StoreConstructor<any>[]): void {
+        storeClasses.forEach(StoreClass => this.register(StoreClass));
+    }
+
+    /**
+     * Get a store instance by its class
+     * Throws if store is not registered
+     * 
+     * @param StoreClass - Store constructor class
+     * @returns Store instance
+     */
+    get<T extends ContextStore<any>>(StoreClass: StoreConstructor<T>): T {
+        const store = this.stores.get(StoreClass);
+        
+        if (!store) {
+            throw new Error(
+                `[StoreRegistry] Store ${StoreClass.name} is not registered. ` +
+                `Make sure to call app.stores([${StoreClass.name}]) before accessing it.`
+            );
+        }
+
+        return store as T;
+    }
+
+    /**
+     * Check if a store is registered
+     * 
+     * @param StoreClass - Store constructor class
+     */
+    has<T extends ContextStore<any>>(StoreClass: StoreConstructor<T>): boolean {
+        return this.stores.has(StoreClass);
+    }
+
+    /**
+     * Get a store instance, or register it if not exists
+     * Useful for lazy initialization
+     * 
+     * @param StoreClass - Store constructor class
+     * @returns Store instance
+     */
+    getOrRegister<T extends ContextStore<any>>(StoreClass: StoreConstructor<T>): T {
+        if (!this.stores.has(StoreClass)) {
+            return this.register(StoreClass);
+        }
+        return this.stores.get(StoreClass) as T;
+    }
+
+    /**
+     * Remove a store from registry and dispose it
+     * 
+     * @param StoreClass - Store constructor class
+     */
+    unregister<T extends ContextStore<any>>(StoreClass: StoreConstructor<T>): void {
+        const store = this.stores.get(StoreClass);
+        
+        if (store) {
+            store.dispose();
+            this.stores.delete(StoreClass);
+            
+            if (this.options.debug) {
+                console.log(`[StoreRegistry] Unregistered store: ${StoreClass.name}`);
+            }
+        }
+    }
+
+    /**
+     * Get all registered store classes
+     */
+    getRegisteredStores(): StoreConstructor<any>[] {
+        return Array.from(this.stores.keys());
+    }
+
+    /**
+     * Get store count
+     */
+    get size(): number {
+        return this.stores.size;
+    }
+
+    /**
+     * Dispose all stores and clear registry
+     */
+    dispose(): void {
+        if (this.options.debug) {
+            console.log(`[StoreRegistry] Disposing all stores (${this.stores.size})`);
+        }
+
+        this.stores.forEach((store, StoreClass) => {
+            try {
+                store.dispose();
+            } catch (error) {
+                console.error(`[StoreRegistry] Error disposing ${StoreClass.name}:`, error);
+            }
+        });
+
+        this.stores.clear();
+    }
+
+    /**
+     * Get debug info about all stores
+     */
+    getDebugInfo(): Record<string, { listenerCount: number; isInitialized: boolean }> {
+        const info: Record<string, { listenerCount: number; isInitialized: boolean }> = {};
+        
+        this.stores.forEach((store, StoreClass) => {
+            info[StoreClass.name] = {
+                listenerCount: store.listenerCount,
+                isInitialized: store.isInitialized
+            };
+        });
+
+        return info;
+    }
+}
+
+/**
+ * Create a new store registry
+ */
+export function createStoreRegistry(options?: StoreRegistryOptions): StoreRegistry {
+    return new StoreRegistry(options);
+}