Add plugin system and update configuration options

Introduces a plugin system to ObjectQL, allowing plugins to extend core functionality via lifecycle hooks. Updates configuration to support connection strings, multiple schema sources, presets, and plugins. Adds documentation for configuration and plugins, and updates example and type definitions accordingly.

Author: hotlong

docs/guide/configuration.md

@@ -0,0 +1,44 @@
+# Configuration
+
+ObjectQL is configured by passing an `ObjectQLConfig` object to the constructor.
+
+## Basic Layout
+
+```typescript
+// objectql.config.ts
+import { ObjectQL } from '@objectql/core';
+
+export const db = new ObjectQL({
+    connection: 'sqlite://data.db', // 1. Infrastructure
+    presets: ['@objectql/preset-auth'], // 2. Base Capabilities
+    source: ['src'], // 3. Application Logic
+    plugins: [] // 4. Extensions
+});
+```
+
+## Reference
+
+### `connection` (string)
+The Connection String URI defining the database connection.
+*   `sqlite://path/to/db`
+*   `postgres://user:pass@host:5432/db`
+*   `mongodb://host:27017/db`
+
+The engine will automatically load the appropriate driver (`@objectql/driver-knex` or `@objectql/driver-mongo`).
+
+### `source` (string | string[])
+One or more directory paths (relative or absolute) containing your schema files (`*.object.yml`).
+The loader scans these directories recursively.
+
+### `presets` (string[])
+A list of NPM packages to load as presets.
+ObjectQL will try to resolve the package and load schema files from its directory.
+Useful for sharing common business objects (User, Role, File, etc.).
+
+### `plugins` (ObjectQLPlugin[])
+A list of plugin instances to extend the core functionality.
+See [Plugin System](./plugins.html) for details.
+
+### `objects` (Record<string, ObjectConfig>)
+(Advanced) In-memory definition of objects. Useful for dynamic runtime schema generation.
+Objects defined here take highest priority.

docs/guide/getting-started.md

@@ -39,38 +39,36 @@ fields:
     default: false
 ```
 
-### 2. Initialize the Engine
+### 2. Configure the Engine
+
+Updated in v0.2: You can now use a simple connection string.
 
 ```typescript
 import { ObjectQL } from '@objectql/core';
-import { KnexDriver } from '@objectql/driver-knex';
+import * as path from 'path';
 
 async function main() {
-    // 1. Configure the engine
-    const app = new ObjectQL({
-        datasources: {
-            default: new KnexDriver({
-                client: 'pg',
-                connection: 'postgres://user:pass@localhost:5432/mydb'
-            })
-        },
-        objects: {
-            // In a real app, you can load these from a directory using app.loadFromDirectory()
-            todo: {
-                name: 'todo',
-                fields: {
-                    title: { type: 'text' },
-                    completed: { type: 'boolean' }
-                }
-            }
-        }
+    const db = new ObjectQL({
+        // 1. Connection String (Protocol://Path)
+        // Detects 'sqlite', 'postgres', 'mongodb' automatically
+        connection: 'sqlite://data.db', 
+        
+        // 2. Schema Source
+        // Where your *.object.yml files are located
+        source: ['src/objects'],
+
+        // 3. Load Presets (Optional)
+        // Load standard objects from npm packages
+        presets: ['@objectql/preset-auth']
     });
 
-    await app.init();
-
-    // 2. Create Data (CRUD)
+    await db.init();
+    
+    // ...
+    
+    // 3. Create Data (CRUD)
     // Create a context (representing a user request)
-    const ctx = app.createContext({}); 
+    const ctx = db.createContext({}); 
     const todoRepo = ctx.object('todo');
 
     const newTask = await todoRepo.create({
@@ -79,7 +77,7 @@ async function main() {
     });
     console.log('Created:', newTask);
 
-    // 3. Query Data
+    // 4. Query Data
     const tasks = await todoRepo.find({
         filters: [['completed', '=', false]]
     });

docs/guide/plugins.md

@@ -0,0 +1,83 @@
+# Plugin System
+
+Plugins allow you to extend the core functionality of ObjectQL by intercepting lifecycle events, modifying metadata, or injecting new services.
+
+## The Plugin Interface
+
+A plugin is simply a class (or object) implementing `ObjectQLPlugin`.
+
+```typescript
+import { IObjectQL } from '@objectql/types';
+
+export interface ObjectQLPlugin {
+    name: string;
+    setup(app: IObjectQL): void | Promise<void>;
+}
+```
+
+The `setup` method is called during `db.init()`, **before** the database drivers are initialized. This gives plugins a chance to modify the schema metadata.
+
+## Capabilities
+
+1.  **Metadata Mutation**: Modify `app.metadata` to inject fields or create objects dynamically.
+2.  **Global Hooks**: Use `app.on()` to listen to events on *all* objects.
+3.  **Action Registry**: Register new actions via `app.registerAction()`.
+
+## Example: Soft Delete Plugin
+
+This plugin automatically handles "Soft Delete" logic:
+1.  Injects an `isDeleted` field to all objects.
+2.  Intercepts `delete` operations to perform an update instead.
+3.  Intercepts `find` operations to filter out deleted records.
+
+```typescript
+import { ObjectQLPlugin, IObjectQL } from '@objectql/types';
+
+export class SoftDeletePlugin implements ObjectQLPlugin {
+    name = 'soft-delete';
+    
+    setup(app: IObjectQL) {
+        // 1. Inject 'isDeleted' field
+        const objects = app.metadata.list('object');
+        for (const obj of objects) {
+            if (!obj.fields.isDeleted) {
+                obj.fields.isDeleted = { type: 'boolean', default: false };
+            }
+        }
+
+        // 2. Intercept DELETE -> UPDATE
+        app.on('before:delete', '*', async (ctx) => {
+            // Prevent actual deletion
+            ctx.preventDefault(); 
+            
+            // Execute internal update
+            // We use a custom action or system updated to bypass recursion if needed
+            await app.executeAction(ctx.objectName, 'internalUpdate', {
+                id: ctx.id,
+                isDeleted: true
+            });
+        });
+
+        // 3. Intercept FIND -> Filter
+        app.on('before:find', '*', async (ctx) => {
+             if (ctx.query) {
+                 ctx.query.filters = {
+                     ...(ctx.query.filters || {}),
+                     isDeleted: false
+                 }
+             }
+        });
+    }
+}
+```
+
+## Usage
+
+```typescript
+const db = new ObjectQL({
+    connection: 'sqlite://data.db',
+    plugins: [
+        new SoftDeletePlugin()
+    ]
+});
+```

examples/project-management/objectql.config.ts

@@ -3,7 +3,8 @@ import * as path from 'path';
 
 const db = new ObjectQL({
     connection: `sqlite://${path.join(__dirname, 'dev.sqlite3')}`,
-    source: path.join(__dirname, 'src')
+    source: ['src'],
+    presets: []
 });
 
 export default db;

packages/core/src/index.ts

@@ -6,6 +6,7 @@ import {
     ObjectQLContextOptions, 
     IObjectQL, 
     ObjectQLConfig,
+    ObjectQLPlugin,
     HookName,
     HookHandler,
     HookContext,
@@ -22,6 +23,7 @@ export class ObjectQL implements IObjectQL {
     private datasources: Record<string, Driver> = {};
     private hooks: Record<string, Array<{ objectName: string, handler: HookHandler }>> = {};
     private actions: Record<string, ActionHandler> = {};
+    private pluginsList: ObjectQLPlugin[] = [];
 
     constructor(config: ObjectQLConfig) {
         this.metadata = config.registry || new MetadataRegistry();
@@ -32,26 +34,48 @@ export class ObjectQL implements IObjectQL {
             this.loadDriverFromConnection(config.connection);
         }
 
+        // 1. Load Presets/Packages first (Base Layer)
+        if (config.packages) {
+            for (const name of config.packages) {
+                this.addPackage(name);
+            }
+        }
+        if (config.presets) {
+            for (const name of config.presets) {
+                this.addPackage(name);
+            }
+        }
+        
+        if (config.plugins) {
+            for (const plugin of config.plugins) {
+                this.use(plugin);
+            }
+        }
+
+        // 2. Load Local Sources (Application Layer - can override presets)
         if (config.source) {
-            this.loader.load(config.source);
+            const sources = Array.isArray(config.source) ? config.source : [config.source];
+            for (const src of sources) {
+                this.loader.load(src);
+            }
         }
 
+        // 3. Load In-Memory Objects (Dynamic Layer - highest priority)
         if (config.objects) {
             for (const [key, obj] of Object.entries(config.objects)) {
                 this.registerObject(obj);
             }
         }
-        if (config.packages) {
-            for (const name of config.packages) {
-                this.addPackage(name);
-            }
-        }
     }
 
     addPackage(name: string) {
         this.loader.loadPackage(name);
     }
 
+    use(plugin: ObjectQLPlugin) {
+        this.pluginsList.push(plugin);
+    }
+
     removePackage(name: string) {
         this.metadata.unregisterPackage(name);
     }
@@ -172,6 +196,12 @@ export class ObjectQL implements IObjectQL {
     }
 
     async init() {
+        // 0. Init Plugins
+        for (const plugin of this.pluginsList) {
+            console.log(`Initializing plugin '${plugin.name}'...`);
+            await plugin.setup(this);
+        }
+
         const objects = this.metadata.list<ObjectConfig>('object');
 
         // 1. Init Drivers (e.g. Sync Schema)

packages/types/src/types.ts

@@ -26,6 +26,11 @@ export interface IObjectRepository {
     execute(actionName: string, id: string | number | undefined, params: any): Promise<any>;
 }
 
+export interface ObjectQLPlugin {
+    name: string;
+    setup(app: IObjectQL): void | Promise<void>;
+}
+
 export interface ObjectQLConfig {
     registry?: MetadataRegistry;
     datasources?: Record<string, Driver>;
@@ -35,11 +40,22 @@ export interface ObjectQLConfig {
      */
     connection?: string;
     /**
-     * Path to the directory containing schema files (*.object.yml).
+     * Path(s) to the directory containing schema files (*.object.yml).
      */
-    source?: string;
+    source?: string | string[];
     objects?: Record<string, ObjectConfig>;
+    /**
+     * @deprecated Use 'presets' instead.
+     */
     packages?: string[];
+    /**
+     * List of npm packages or presets to load.
+     */
+    presets?: string[];
+    /**
+     * List of plugins to load.
+     */
+    plugins?: ObjectQLPlugin[];
 }
 
 export interface IObjectQL {