@engjts/nexus 0.1.8 → 0.1.10

package/src/core/plugin/builder.ts

@@ -1,358 +0,0 @@
-/**
- * Plugin Builder
- * Fluent API for creating plugins with type safety
- */
-
-import {
-    NexusPlugin,
-    PluginMeta,
-    PluginContext,
-    PluginRouteExtension,
-    PluginPriority,
-    PluginFactory
-} from './types';
-import { Context, Middleware, Handler, Response } from '../types';
-
-/**
- * Plugin Builder for fluent plugin creation
- * 
- * @example
- * ```typescript
- * const authPlugin = definePlugin('auth-plugin')
- *   .version('1.0.0')
- *   .description('Authentication plugin with JWT support')
- *   .depends(['database-plugin'])
- *   .config<{ secret: string; expiry: number }>()
- *   .defaults({ expiry: 3600 })
- *   .middleware((ctx) => jwtMiddleware(ctx.config.secret))
- *   .decorate((ctx) => {
- *     ctx.auth = { user: null, isAuthenticated: false };
- *   })
- *   .register(async (ctx) => {
- *     ctx.log.info('Auth plugin initialized');
- *   })
- *   .export((ctx) => ({
- *     verify: (token: string) => verifyJWT(token, ctx.config.secret),
- *     sign: (payload: any) => signJWT(payload, ctx.config.secret)
- *   }))
- *   .build();
- * ```
- */
-export class PluginBuilder<TConfig = {}, TExports = {}> {
-    private _meta: PluginMeta;
-    private _defaults?: Partial<TConfig>;
-    private _validateConfig?: (config: TConfig) => boolean | string;
-    private _configure?: (ctx: PluginContext<TConfig>) => void | Promise<void>;
-    private _register?: (ctx: PluginContext<TConfig>) => void | Promise<void>;
-    private _boot?: (ctx: PluginContext<TConfig>) => void | Promise<void>;
-    private _ready?: (ctx: PluginContext<TConfig>) => void | Promise<void>;
-    private _shutdown?: (ctx: PluginContext<TConfig>) => void | Promise<void>;
-    private _exports?: (ctx: PluginContext<TConfig>) => TExports;
-    private _middlewares?: Middleware[] | ((ctx: PluginContext<TConfig>) => Middleware[]);
-    private _routes?: PluginRouteExtension[] | ((ctx: PluginContext<TConfig>) => PluginRouteExtension[]);
-    private _decorateContext?: (ctx: Context) => void;
-    private _decorateApp?: (app: any) => void;
-
-    constructor(name: string) {
-        this._meta = { name, version: '1.0.0' };
-    }
-
-    /**
-     * Set plugin version
-     */
-    version(version: string): this {
-        this._meta.version = version;
-        return this;
-    }
-
-    /**
-     * Set plugin description
-     */
-    description(description: string): this {
-        this._meta.description = description;
-        return this;
-    }
-
-    /**
-     * Set plugin author
-     */
-    author(author: string | { name: string; email?: string; url?: string }): this {
-        this._meta.author = author;
-        return this;
-    }
-
-    /**
-     * Set plugin homepage
-     */
-    homepage(url: string): this {
-        this._meta.homepage = url;
-        return this;
-    }
-
-    /**
-     * Set plugin priority
-     */
-    priority(priority: PluginPriority): this {
-        this._meta.priority = priority;
-        return this;
-    }
-
-    /**
-     * Add tags for categorization
-     */
-    tags(...tags: string[]): this {
-        this._meta.tags = tags;
-        return this;
-    }
-
-    /**
-     * Declare required dependencies
-     */
-    depends(plugins: string[]): this {
-        this._meta.dependencies = plugins;
-        return this;
-    }
-
-    /**
-     * Declare optional dependencies
-     */
-    optionalDeps(plugins: string[]): this {
-        this._meta.optionalDependencies = plugins;
-        return this;
-    }
-
-    /**
-     * Declare conflicting plugins
-     */
-    conflicts(plugins: string[]): this {
-        this._meta.conflicts = plugins;
-        return this;
-    }
-
-    /**
-     * Define config type (for TypeScript inference)
-     */
-    config<T>(): PluginBuilder<T, TExports> {
-        return this as unknown as PluginBuilder<T, TExports>;
-    }
-
-    /**
-     * Set default configuration
-     */
-    defaults(defaults: Partial<TConfig>): this {
-        this._defaults = defaults;
-        return this;
-    }
-
-    /**
-     * Add config validator
-     */
-    validate(validator: (config: TConfig) => boolean | string): this {
-        this._validateConfig = validator;
-        return this;
-    }
-
-    /**
-     * Configure phase hook
-     */
-    configure(fn: (ctx: PluginContext<TConfig>) => void | Promise<void>): this {
-        this._configure = fn;
-        return this;
-    }
-
-    /**
-     * Register phase hook
-     */
-    register(fn: (ctx: PluginContext<TConfig>) => void | Promise<void>): this {
-        this._register = fn;
-        return this;
-    }
-
-    /**
-     * Boot phase hook
-     */
-    boot(fn: (ctx: PluginContext<TConfig>) => void | Promise<void>): this {
-        this._boot = fn;
-        return this;
-    }
-
-    /**
-     * Ready phase hook
-     */
-    ready(fn: (ctx: PluginContext<TConfig>) => void | Promise<void>): this {
-        this._ready = fn;
-        return this;
-    }
-
-    /**
-     * Shutdown phase hook
-     */
-    shutdown(fn: (ctx: PluginContext<TConfig>) => void | Promise<void>): this {
-        this._shutdown = fn;
-        return this;
-    }
-
-    /**
-     * Define exports for other plugins
-     */
-    export<T>(fn: (ctx: PluginContext<TConfig>) => T): PluginBuilder<TConfig, T> {
-        this._exports = fn as any;
-        return this as unknown as PluginBuilder<TConfig, T>;
-    }
-
-    /**
-     * Add global middleware
-     */
-    middleware(middleware: Middleware | ((ctx: PluginContext<TConfig>) => Middleware)): this {
-        if (!this._middlewares) {
-            this._middlewares = [];
-        }
-        if (typeof middleware === 'function' && middleware.length === 1) {
-            // It's a factory function
-            const existing = this._middlewares;
-            this._middlewares = (ctx: PluginContext<TConfig>) => {
-                const base = typeof existing === 'function' ? existing(ctx) : existing;
-                return [...base, (middleware as (ctx: PluginContext<TConfig>) => Middleware)(ctx)];
-            };
-        } else {
-            if (Array.isArray(this._middlewares)) {
-                this._middlewares.push(middleware as Middleware);
-            }
-        }
-        return this;
-    }
-
-    /**
-     * Add multiple middlewares
-     */
-    middlewares(middlewares: Middleware[] | ((ctx: PluginContext<TConfig>) => Middleware[])): this {
-        this._middlewares = middlewares;
-        return this;
-    }
-
-    /**
-     * Add a route
-     */
-    route(
-        method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',
-        path: string,
-        handler: Handler,
-        options?: { middlewares?: Middleware[]; meta?: PluginRouteExtension['meta'] }
-    ): this {
-        if (!this._routes) {
-            this._routes = [];
-        }
-        if (Array.isArray(this._routes)) {
-            this._routes.push({
-                method,
-                path,
-                handler,
-                middlewares: options?.middlewares,
-                meta: options?.meta
-            });
-        }
-        return this;
-    }
-
-    /**
-     * Add routes dynamically
-     */
-    routes(routes: PluginRouteExtension[] | ((ctx: PluginContext<TConfig>) => PluginRouteExtension[])): this {
-        this._routes = routes;
-        return this;
-    }
-
-    /**
-     * Decorate request context
-     */
-    decorate(decorator: (ctx: Context) => void): this {
-        this._decorateContext = decorator;
-        return this;
-    }
-
-    /**
-     * Decorate application
-     */
-    decorateApp(decorator: (app: any) => void): this {
-        this._decorateApp = decorator;
-        return this;
-    }
-
-    /**
-     * Build the plugin
-     */
-    build(): NexusPlugin<TConfig, TExports> {
-        return {
-            meta: this._meta,
-            defaults: this._defaults,
-            validateConfig: this._validateConfig,
-            configure: this._configure,
-            register: this._register,
-            boot: this._boot,
-            ready: this._ready,
-            shutdown: this._shutdown,
-            exports: this._exports,
-            middlewares: this._middlewares,
-            routes: this._routes,
-            decorateContext: this._decorateContext,
-            decorateApp: this._decorateApp
-        };
-    }
-
-    /**
-     * Build as factory function (accepts config at runtime)
-     */
-    factory(): PluginFactory<TConfig> {
-        return (config?: TConfig) => {
-            const plugin = this.build();
-            // Config will be merged by PluginManager
-            return plugin;
-        };
-    }
-}
-
-/**
- * Create a new plugin using fluent builder
- * 
- * @example
- * ```typescript
- * const myPlugin = definePlugin('my-plugin')
- *   .version('1.0.0')
- *   .register(async (ctx) => {
- *     ctx.log.info('Hello from my plugin!');
- *   })
- *   .build();
- * 
- * app.plugin(myPlugin);
- * ```
- */
-export function definePlugin(name: string): PluginBuilder {
-    return new PluginBuilder(name);
-}
-
-/**
- * Create a simple plugin quickly
- * 
- * @example
- * ```typescript
- * const loggerPlugin = createPlugin({
- *   name: 'logger',
- *   version: '1.0.0',
- *   register: (ctx) => {
- *     ctx.app.use(loggerMiddleware);
- *   }
- * });
- * ```
- */
-export function createPlugin<TConfig = any, TExports = any>(
-    options: Partial<NexusPlugin<TConfig, TExports>> & { name: string }
-): NexusPlugin<TConfig, TExports> {
-    return {
-        meta: {
-            name: options.name,
-            version: options.meta?.version ?? '1.0.0',
-            ...options.meta
-        },
-        ...options
-    } as NexusPlugin<TConfig, TExports>;
-}

package/src/core/plugin/index.ts

@@ -1,50 +0,0 @@
-/**
- * Plugin System - Public API
- * 
- * @example
- * ```typescript
- * import { definePlugin, createPlugin, PluginManager } from '@engjts/server/plugin';
- * 
- * // Using fluent builder
- * const authPlugin = definePlugin('auth')
- *   .version('1.0.0')
- *   .config<{ secret: string }>()
- *   .register(ctx => {
- *     ctx.log.info('Auth initialized');
- *   })
- *   .build();
- * 
- * // Using quick create
- * const loggerPlugin = createPlugin({
- *   name: 'logger',
- *   register: ctx => ctx.app.use(logMiddleware)
- * });
- * 
- * app.plugin(authPlugin, { secret: 'xxx' });
- * app.plugin(loggerPlugin);
- * ```
- */
-
-// Types
-export type {
-    NexusPlugin,
-    SimplePlugin,
-    PluginFactory,
-    PluginMeta,
-    PluginContext,
-    PluginLogger,
-    PluginPhase,
-    PluginPriority,
-    PluginRouteExtension,
-    PluginManagerEvents,
-    RegisteredPlugin
-} from './types';
-
-// Plugin Manager
-export { PluginManager } from './PluginManager';
-
-// Builder & Factories
-export { PluginBuilder, definePlugin, createPlugin } from './builder';
-
-// Constants
-export { PRIORITY_WEIGHTS } from './types';

package/src/core/plugin/types.ts

@@ -1,214 +0,0 @@
-/**
- * Plugin System Types
- * Advanced plugin architecture for Nexus Framework
- */
-
-import { Application } from '../application';
-import { Context, Middleware, Handler, Response } from '../types';
-
-/**
- * Plugin lifecycle phases
- */
-export type PluginPhase = 
-    | 'configure'    // Before app starts, configure settings
-    | 'register'     // Register routes, middlewares, stores
-    | 'boot'         // After all plugins registered, before server starts
-    | 'ready'        // Server is listening
-    | 'shutdown';    // App is shutting down
-
-/**
- * Plugin priority levels
- */
-export type PluginPriority = 'critical' | 'high' | 'normal' | 'low';
-
-/**
- * Plugin metadata
- */
-export interface PluginMeta {
-    /** Unique plugin name */
-    name: string;
-    /** Plugin version (semver) */
-    version: string;
-    /** Plugin description */
-    description?: string;
-    /** Author information */
-    author?: string | { name: string; email?: string; url?: string };
-    /** Plugin homepage/docs URL */
-    homepage?: string;
-    /** Plugin dependencies (other plugin names) */
-    dependencies?: string[];
-    /** Optional dependencies (won't fail if missing) */
-    optionalDependencies?: string[];
-    /** Plugins that conflict with this one */
-    conflicts?: string[];
-    /** Plugin priority */
-    priority?: PluginPriority;
-    /** Plugin tags for categorization */
-    tags?: string[];
-}
-
-/**
- * Plugin context passed to lifecycle hooks
- * @template TConfig - The plugin's configuration type
- */
-export interface PluginContext<TConfig = Record<string, any>> {
-    /** The application instance */
-    app: Application<any>;
-    /** Plugin's own configuration (passed during .plugin()) */
-    config: TConfig;
-    /** Access other plugin's exported APIs */
-    getPlugin<T = any>(name: string): T | undefined;
-    /** Check if a plugin is installed */
-    hasPlugin(name: string): boolean;
-    /** Logger scoped to this plugin */
-    log: PluginLogger;
-    /** Plugin-scoped storage (persists across lifecycle) */
-    storage: Map<string, any>;
-}
-
-/**
- * Plugin logger interface
- */
-export interface PluginLogger {
-    debug(message: string, ...args: any[]): void;
-    info(message: string, ...args: any[]): void;
-    warn(message: string, ...args: any[]): void;
-    error(message: string, ...args: any[]): void;
-}
-
-/**
- * Route extension added by plugin
- */
-export interface PluginRouteExtension {
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
-    path: string;
-    handler: Handler;
-    middlewares?: Middleware[];
-    meta?: {
-        description?: string;
-        tags?: string[];
-        internal?: boolean;
-    };
-}
-
-/**
- * Full plugin interface
- */
-export interface NexusPlugin<TConfig = any, TExports = any> {
-    /** Plugin metadata */
-    meta: PluginMeta;
-    
-    /** Default configuration */
-    defaults?: Partial<TConfig>;
-    
-    /** Validate plugin configuration */
-    validateConfig?: (config: TConfig) => boolean | string;
-    
-    /**
-     * Configure phase - set up configuration before anything else
-     * Called in dependency order
-     */
-    configure?: (ctx: PluginContext<TConfig>) => void | Promise<void>;
-    
-    /**
-     * Register phase - register routes, middleware, stores, etc.
-     * Called after all plugins are configured
-     */
-    register?: (ctx: PluginContext<TConfig>) => void | Promise<void>;
-    
-    /**
-     * Boot phase - perform initialization after all registrations
-     * Called after all plugins are registered
-     */
-    boot?: (ctx: PluginContext<TConfig>) => void | Promise<void>;
-    
-    /**
-     * Ready phase - called when server is listening
-     * Good for logging, connecting to external services
-     */
-    ready?: (ctx: PluginContext<TConfig>) => void | Promise<void>;
-    
-    /**
-     * Shutdown phase - cleanup when app is shutting down
-     * Called in reverse dependency order
-     */
-    shutdown?: (ctx: PluginContext<TConfig>) => void | Promise<void>;
-    
-    /**
-     * Export APIs for other plugins to use
-     * Accessible via ctx.getPlugin('plugin-name')
-     */
-    exports?: (ctx: PluginContext<TConfig>) => TExports;
-    
-    /**
-     * Middleware to add globally
-     */
-    middlewares?: Middleware[] | ((ctx: PluginContext<TConfig>) => Middleware[]);
-    
-    /**
-     * Routes to add
-     */
-    routes?: PluginRouteExtension[] | ((ctx: PluginContext<TConfig>) => PluginRouteExtension[]);
-    
-    /**
-     * Decorate the Context with additional properties/methods
-     */
-    decorateContext?: (ctx: Context) => void;
-    
-    /**
-     * Decorate the Application with additional methods
-     */
-    decorateApp?: (app: Application<any>) => void;
-}
-
-/**
- * Simplified plugin using just an install function (legacy compatible)
- */
-export interface SimplePlugin {
-    name: string;
-    version: string;
-    install: (app: Application<any>) => void | Promise<void>;
-}
-
-/**
- * Plugin factory function type
- */
-export type PluginFactory<TConfig = any> = (config?: TConfig) => NexusPlugin<TConfig>;
-
-/**
- * Registered plugin entry
- */
-export interface RegisteredPlugin {
-    meta: PluginMeta;
-    plugin: NexusPlugin<any, any>;
-    config: Record<string, any>;
-    exports?: any;
-    storage: Map<string, any>;
-    state: 'pending' | 'configured' | 'registered' | 'booted' | 'ready' | 'shutdown' | 'error';
-    error?: Error;
-}
-
-/**
- * Plugin manager events
- */
-export interface PluginManagerEvents {
-    'plugin:added': (meta: PluginMeta) => void;
-    'plugin:configured': (meta: PluginMeta) => void;
-    'plugin:registered': (meta: PluginMeta) => void;
-    'plugin:booted': (meta: PluginMeta) => void;
-    'plugin:ready': (meta: PluginMeta) => void;
-    'plugin:shutdown': (meta: PluginMeta) => void;
-    'plugin:error': (meta: PluginMeta, error: Error) => void;
-    'lifecycle:start': (phase: PluginPhase) => void;
-    'lifecycle:complete': (phase: PluginPhase) => void;
-}
-
-/**
- * Priority weights for sorting
- */
-export const PRIORITY_WEIGHTS: Record<PluginPriority, number> = {
-    critical: 0,
-    high: 1,
-    normal: 2,
-    low: 3
-};