@dataql/node/dist/esm/lib/plugins/types.d.ts

DataQL core SDK for unified data management with MongoDB and GraphQL - Production Multi-Cloud Ready

/**
 * DataQL Plugin System Types and Interfaces
 *
 * This defines the complete plugin architecture for DataQL, allowing
 * developers to extend functionality, add database adapters, integrate
 * third-party services, and build custom extensions.
 */
import { Data } from "../Data.js";
/**
 * Base plugin interface that all plugins must implement
 */
export interface Plugin {
    /** Unique plugin identifier */
    id: string;
    /** Human-readable plugin name */
    name: string;
    /** Plugin version */
    version: string;
    /** Plugin description */
    description: string;
    /** Plugin author */
    author: string;
    /** Plugin type */
    type: PluginType;
    /** Plugin dependencies */
    dependencies?: string[];
    /** Plugin configuration schema */
    configSchema?: Record<string, any>;
    /** Plugin initialization */
    initialize(context: PluginContext): Promise<void> | void;
    /** Plugin cleanup */
    destroy?(): Promise<void> | void;
}
/**
 * Plugin types supported by DataQL
 */
export type PluginType = "adapter" | "middleware" | "extension" | "transform" | "validator" | "hook" | "integration" | "analytics" | "security" | "cache" | "sync" | "ui";
/**
 * Plugin context provided during initialization
 */
export interface PluginContext {
    /** DataQL instance */
    dataql: Data;
    /** Plugin configuration */
    config: Record<string, any>;
    /** Plugin manager instance */
    pluginManager: PluginManager;
    /** Logger instance */
    logger: PluginLogger;
    /** Event system */
    events: PluginEventSystem;
    /** Utility functions */
    utils: PluginUtils;
}
/**
 * Plugin manager interface
 */
export interface PluginManager {
    /** Register a plugin */
    register(plugin: Plugin, config?: Record<string, any>): Promise<void>;
    /** Unregister a plugin */
    unregister(pluginId: string): Promise<void>;
    /** Get registered plugin */
    getPlugin(pluginId: string): Plugin | undefined;
    /** Get all registered plugins */
    getPlugins(): Plugin[];
    /** Get plugins by type */
    getPluginsByType(type: PluginType): Plugin[];
    /** Check if plugin is registered */
    hasPlugin(pluginId: string): boolean;
    /** Initialize all plugins */
    initializeAll(): Promise<void>;
    /** Destroy all plugins */
    destroyAll(): Promise<void>;
}
/**
 * Database adapter plugin interface
 */
export interface DatabaseAdapterPlugin extends Plugin {
    type: "adapter";
    /** Database type this adapter supports */
    databaseType: string;
    /** Create connection */
    createConnection(connectionString: string): Promise<DatabaseConnection>;
    /** Introspect database */
    introspect(connection: DatabaseConnection, options?: any): Promise<any>;
    /** Execute query */
    executeQuery(connection: DatabaseConnection, query: any): Promise<any>;
    /** Close connection */
    closeConnection(connection: DatabaseConnection): Promise<void>;
}
/**
 * Database connection interface
 */
export interface DatabaseConnection {
    id: string;
    type: string;
    isConnected: boolean;
    connect(): Promise<void>;
    disconnect(): Promise<void>;
    ping(): Promise<boolean>;
}
/**
 * Middleware plugin interface
 */
export interface MiddlewarePlugin extends Plugin {
    type: "middleware";
    /** Middleware execution order (lower = earlier) */
    order: number;
    /** Process request */
    processRequest?(request: PluginRequest): Promise<PluginRequest>;
    /** Process response */
    processResponse?(response: PluginResponse): Promise<PluginResponse>;
    /** Handle errors */
    handleError?(error: Error, context: any): Promise<any>;
}
/**
 * Plugin request interface
 */
export interface PluginRequest {
    id: string;
    method: string;
    url: string;
    headers: Record<string, string>;
    body: any;
    params: Record<string, any>;
    query: Record<string, any>;
    timestamp: Date;
    metadata: Record<string, any>;
}
/**
 * Plugin response interface
 */
export interface PluginResponse {
    status: number;
    headers: Record<string, string>;
    body: any;
    metadata: Record<string, any>;
    timestamp: Date;
}
/**
 * Extension plugin interface
 */
export interface ExtensionPlugin extends Plugin {
    type: "extension";
    /** Extension methods to add to DataQL */
    methods?: Record<string, Function>;
    /** Extension properties to add to DataQL */
    properties?: Record<string, any>;
    /** Collection extensions */
    collectionExtensions?: Record<string, Function>;
}
/**
 * Hook plugin interface
 */
export interface HookPlugin extends Plugin {
    type: "hook";
    /** Hook handlers */
    hooks: Record<string, HookHandler>;
}
/**
 * Hook handler function
 */
export type HookHandler = (data: any, context: HookContext) => Promise<any> | any;
/**
 * Hook context
 */
export interface HookContext {
    hookName: string;
    pluginId: string;
    dataql: Data;
    metadata: Record<string, any>;
}
/**
 * Integration plugin interface
 */
export interface IntegrationPlugin extends Plugin {
    type: "integration";
    /** Service this plugin integrates with */
    service: string;
    /** API client */
    client?: any;
    /** Sync data to external service */
    syncTo?(data: any, options?: any): Promise<any>;
    /** Sync data from external service */
    syncFrom?(options?: any): Promise<any>;
    /** Setup webhooks */
    setupWebhooks?(endpoints: string[]): Promise<void>;
}
/**
 * Plugin event system
 */
export interface PluginEventSystem {
    /** Emit an event */
    emit(event: string, data: any): void;
    /** Listen to an event */
    on(event: string, handler: (data: any) => void): void;
    /** Listen to an event once */
    once(event: string, handler: (data: any) => void): void;
    /** Remove event listener */
    off(event: string, handler?: (data: any) => void): void;
    /** Get event listeners */
    listeners(event: string): Function[];
}
/**
 * Plugin logger interface
 */
export interface PluginLogger {
    debug(message: string, meta?: any): void;
    info(message: string, meta?: any): void;
    warn(message: string, meta?: any): void;
    error(message: string, meta?: any): void;
    child(context: Record<string, any>): PluginLogger;
}
/**
 * Plugin utilities
 */
export interface PluginUtils {
    /** Generate unique ID */
    generateId(): string;
    /** Validate configuration */
    validateConfig(config: any, schema: any): boolean;
    /** Merge configurations */
    mergeConfig(base: any, override: any): any;
    /** Deep clone object */
    clone<T>(obj: T): T;
    /** Check if object is empty */
    isEmpty(obj: any): boolean;
    /** Retry operation */
    retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
}
/**
 * Retry options
 */
export interface RetryOptions {
    attempts: number;
    delay: number;
    backoff?: "linear" | "exponential";
}
/**
 * Plugin manifest for package.json
 */
export interface PluginManifest {
    dataql: {
        plugin: {
            type: PluginType;
            entry: string;
            name: string;
            description: string;
            version: string;
            author: string;
            dependencies?: string[];
            config?: Record<string, any>;
            hooks?: string[];
            methods?: string[];
            collections?: string[];
        };
    };
}
/**
 * Plugin registry interface
 */
export interface PluginRegistry {
    /** Search for plugins */
    search(query: string, type?: PluginType): Promise<PluginInfo[]>;
    /** Get plugin information */
    getPluginInfo(pluginId: string): Promise<PluginInfo>;
    /** Install plugin */
    install(pluginId: string, version?: string): Promise<void>;
    /** Uninstall plugin */
    uninstall(pluginId: string): Promise<void>;
    /** List installed plugins */
    listInstalled(): Promise<PluginInfo[]>;
    /** Update plugin */
    update(pluginId: string, version?: string): Promise<void>;
    /** Publish plugin */
    publish(plugin: Plugin, manifest: PluginManifest): Promise<void>;
}
/**
 * Plugin information
 */
export interface PluginInfo {
    id: string;
    name: string;
    description: string;
    version: string;
    author: string;
    type: PluginType;
    downloads: number;
    rating: number;
    tags: string[];
    repository: string;
    homepage: string;
    license: string;
    dependencies: string[];
    peerDependencies: string[];
    createdAt: Date;
    updatedAt: Date;
}
/**
 * Plugin configuration
 */
export interface PluginConfig {
    /** Plugin ID */
    id: string;
    /** Plugin configuration */
    config: Record<string, any>;
    /** Whether plugin is enabled */
    enabled: boolean;
    /** Plugin load order */
    order?: number;
}
/**
 * Plugin discovery options
 */
export interface PluginDiscoveryOptions {
    /** Directories to search for plugins */
    directories: string[];
    /** Plugin patterns */
    patterns: string[];
    /** Auto-install missing plugins */
    autoInstall: boolean;
    /** Registry URL */
    registryUrl: string;
}
/**
 * DataQL hooks (events that plugins can listen to)
 */
export type DataQLHook = "beforeRequest" | "afterRequest" | "beforeCreate" | "afterCreate" | "beforeRead" | "afterRead" | "beforeUpdate" | "afterUpdate" | "beforeDelete" | "afterDelete" | "beforeTransaction" | "afterTransaction" | "beforeIntrospection" | "afterIntrospection" | "beforeMigration" | "afterMigration" | "onError" | "onConnect" | "onDisconnect" | "onSessionCreate" | "onSessionDestroy" | "onSchemaChange" | "onDataChange";
/**
 * Hook data interfaces
 */
export interface HookData {
    beforeRequest: {
        request: PluginRequest;
    };
    afterRequest: {
        request: PluginRequest;
        response: PluginResponse;
    };
    beforeCreate: {
        collection: string;
        data: any;
    };
    afterCreate: {
        collection: string;
        data: any;
        result: any;
    };
    beforeRead: {
        collection: string;
        filter: any;
    };
    afterRead: {
        collection: string;
        filter: any;
        result: any;
    };
    beforeUpdate: {
        collection: string;
        filter: any;
        update: any;
    };
    afterUpdate: {
        collection: string;
        filter: any;
        update: any;
        result: any;
    };
    beforeDelete: {
        collection: string;
        filter: any;
    };
    afterDelete: {
        collection: string;
        filter: any;
        result: any;
    };
    beforeTransaction: {
        operations: any[];
    };
    afterTransaction: {
        operations: any[];
        result: any;
    };
    beforeIntrospection: {
        databaseUrl: string;
        options: any;
    };
    afterIntrospection: {
        databaseUrl: string;
        options: any;
        result: any;
    };
    beforeMigration: {
        databaseUrl: string;
        options: any;
    };
    afterMigration: {
        databaseUrl: string;
        options: any;
        result: any;
    };
    onError: {
        error: Error;
        context: any;
    };
    onConnect: {
        connectionString: string;
    };
    onDisconnect: {
        connectionString: string;
    };
    onSessionCreate: {
        sessionId: string;
    };
    onSessionDestroy: {
        sessionId: string;
    };
    onSchemaChange: {
        collection: string;
        oldSchema: any;
        newSchema: any;
    };
    onDataChange: {
        collection: string;
        operation: string;
        data: any;
    };
}