@objectql/platform-node 1.6.0

package/src/driver.ts

@@ -0,0 +1,54 @@
+import { Driver } from '@objectql/types';
+
+export function createDriverFromConnection(connection: string): Driver {
+    let driverPackage = '';
+    let driverClass = '';
+    let driverConfig: any = {};
+    
+    if (connection.startsWith('mongodb://')) {
+        driverPackage = '@objectql/driver-mongo';
+        driverClass = 'MongoDriver';
+        driverConfig = { url: connection };
+    } 
+    else if (connection.startsWith('sqlite://')) {
+        driverPackage = '@objectql/driver-sql';
+        driverClass = 'KnexDriver';
+        const filename = connection.replace('sqlite://', '');
+        driverConfig = {
+            client: 'sqlite3',
+            connection: { filename },
+            useNullAsDefault: true
+        };
+    }
+    else if (connection.startsWith('postgres://') || connection.startsWith('postgresql://')) {
+        driverPackage = '@objectql/driver-sql';
+        driverClass = 'KnexDriver';
+        driverConfig = {
+            client: 'pg',
+            connection: connection
+        };
+    }
+    else if (connection.startsWith('mysql://')) {
+        driverPackage = '@objectql/driver-sql';
+        driverClass = 'KnexDriver';
+        driverConfig = {
+            client: 'mysql2',
+            connection: connection
+        };
+    }
+    else {
+        throw new Error(`Unsupported connection protocol: ${connection}`);
+    }
+
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const pkg = require(driverPackage);
+        const DriverClass = pkg[driverClass];
+        if (!DriverClass) {
+            throw new Error(`${driverClass} not found in ${driverPackage}`);
+        }
+        return new DriverClass(driverConfig);
+    } catch (e: any) {
+        throw new Error(`Failed to load driver ${driverPackage}. Please install it: npm install ${driverPackage}. Error: ${e.message}`);
+    }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './loader';
+export * from './plugin';
+export * from './driver';

package/src/loader.ts

@@ -0,0 +1,349 @@
+import * as fs from 'fs';
+import * as glob from 'fast-glob';
+import * as path from 'path';
+import { MetadataRegistry, ObjectConfig, LoaderPlugin, LoaderHandlerContext, FieldConfig } from '@objectql/types';
+import * as yaml from 'js-yaml';
+import { toTitleCase } from '@objectql/core';
+
+export class ObjectLoader {
+    private plugins: LoaderPlugin[] = [];
+
+    constructor(protected registry: MetadataRegistry) {
+        this.registerBuiltinPlugins();
+    }
+
+    private registerBuiltinPlugins() {
+        // Objects
+        this.use({
+            name: 'object',
+            glob: ['**/*.object.yml', '**/*.object.yaml'],
+            handler: (ctx) => {
+                try {
+                    const doc = yaml.load(ctx.content) as any;
+                    if (!doc) return;
+
+                    // Calculate ID from filename
+                    const basename = path.basename(ctx.file);
+                    const filenameId = basename.replace(/\.object\.(yml|yaml)$/, '');
+
+                    // 1. Single Object definition (Standard)
+                    // If fields are present, we treat it as a single object definition
+                    if (doc.fields) {
+                        if (!doc.name) {
+                            // If name is missing, infer from filename
+                            doc.name = filenameId;
+                        } else if (doc.name !== filenameId) {
+                            // warn if mismatch
+                            console.warn(`[ObjectQL] Warning: Object name '${doc.name}' in ${basename} does not match filename. Using '${doc.name}'.`);
+                        }
+
+                        const packageEntry = ctx.registry.getEntry('package-map', ctx.file);
+                        registerObject(ctx.registry, doc, ctx.file, ctx.packageName || (packageEntry && packageEntry.package));
+                        return;
+                    }
+
+                     // 2. Multi-object map (Legacy/Bundle mode) 
+                    // e.g. { object1: { fields... }, object2: { fields... } }
+                    for (const [key, value] of Object.entries(doc)) {
+                        if (typeof value === 'object' && (value as any).fields) {
+                            const obj = value as any;
+                            if (!obj.name) obj.name = key;
+                            registerObject(ctx.registry, obj, ctx.file, ctx.packageName);
+                        }
+                    }
+                } catch (e) {
+                    console.error(`Error loading object from ${ctx.file}:`, e);
+                }
+            }
+        });
+
+        // Hooks
+        this.use({
+            name: 'hook',
+            glob: ['**/*.hook.ts', '**/*.hook.js'],
+            handler: (ctx) => {
+                const basename = path.basename(ctx.file);
+                // Extract object name from filename: user.hook.ts -> user
+                const objectName = basename.replace(/\.hook\.(ts|js)$/, '');
+                
+                try {
+                    const mod = require(ctx.file);
+                    // Support default export or named exports
+                    const hooks = mod.default || mod;
+                    
+                    ctx.registry.register('hook', {
+                        type: 'hook',
+                        id: objectName, // Hook ID is the object name
+                        path: ctx.file,
+                        package: ctx.packageName,
+                        content: hooks
+                    });
+                } catch (e) {
+                    console.error(`Error loading hook from ${ctx.file}:`, e);
+                }
+            }
+        });
+        
+        // Actions
+        this.use({
+            name: 'action',
+            glob: ['**/*.action.ts', '**/*.action.js'],
+            handler: (ctx) => {
+                const basename = path.basename(ctx.file);
+                // Extract object name: invoice.action.ts -> invoice
+                const objectName = basename.replace(/\.action\.(ts|js)$/, '');
+                
+                try {
+                    const mod = require(ctx.file);
+
+                    const actions: Record<string, any> = {};
+                    
+                    for (const [key, value] of Object.entries(mod)) {
+                        if (key === 'default') continue;
+                        if (typeof value === 'object' && (value as any).handler) {
+                            actions[key] = value;
+                        }
+                    }
+                    
+                    if (Object.keys(actions).length > 0) {
+                         ctx.registry.register('action', {
+                            type: 'action',
+                            id: objectName, // Action collection ID is the object name
+                            path: ctx.file,
+                            package: ctx.packageName,
+                            content: actions
+                        });
+                    }
+
+                } catch (e) {
+                    console.error(`Error loading action from ${ctx.file}:`, e);
+                }
+            }
+        });
+
+        // Generic YAML Metadata Loaders
+        const metaTypes = ['view', 'form', 'permission', 'report', 'workflow', 'validation', 'data', 'app', 'page', 'menu'];
+        
+        for (const type of metaTypes) {
+            this.use({
+                name: type,
+                glob: [`**/*.${type}.yml`, `**/*.${type}.yaml`],
+                handler: (ctx) => {
+                    try {
+                        const doc = yaml.load(ctx.content) as any;
+                        if (!doc) return;
+
+                        // Use 'name' from doc, or filename base (without extension)
+                        let id = doc.name;
+                        if (!id) {
+                            const basename = path.basename(ctx.file); 
+                            // e.g. "my-view.view.yml" -> "my-view"
+                            // Regex: remove .type.yml or .type.yaml
+                            const re = new RegExp(`\\.${type}\\.(yml|yaml)$`);
+                            id = basename.replace(re, '');
+                        }
+
+                        // Ensure name is in the doc for consistency
+                        if (!doc.name) doc.name = id;
+
+                        ctx.registry.register(type, {
+                            type: type,
+                            id: id,
+                            path: ctx.file,
+                            package: ctx.packageName,
+                            content: doc
+                        });
+                    } catch (e) {
+                         console.error(`Error loading ${type} from ${ctx.file}:`, e);
+                    }
+                }
+            })
+        }
+    }
+
+    use(plugin: LoaderPlugin) {
+        this.plugins.push(plugin);
+    }
+
+    load(dir: string, packageName?: string) {
+        for (const plugin of this.plugins) {
+            this.runPlugin(plugin, dir, packageName);
+        }
+    }
+
+    loadPackage(packageName: string) {
+        try {
+            const entryPath = require.resolve(packageName, { paths: [process.cwd()] });
+            // clean cache
+            delete require.cache[entryPath];
+            const packageDir = path.dirname(entryPath);
+            this.load(packageDir, packageName);
+        } catch (e) {
+            // fallback to directory
+            this.load(packageName, packageName);
+        }
+    }
+
+    private runPlugin(plugin: LoaderPlugin, dir: string, packageName?: string) {
+        // Enforce path conventions: 
+        // 1. Never scan node_modules (unless explicitly loaded via loadPackage which sets cwd inside it)
+        // 2. Ignore build artifacts (dist, build, out) to avoid double-loading metadata if both src and dist exist.
+        //    Note: If you want to load from 'dist', you must explicitly point the loader to it (e.g. loader.load('./dist')).
+        //    In that case, the patterns won't match relative to the CWD.
+        // Path conventions:
+        // 1. Always ignore node_modules and .git
+        const ignore = [
+            '**/node_modules/**', 
+            '**/.git/**'
+        ];
+
+        // 2. Intelligent handling of build artifacts (dist/build)
+        // If 'src' exists in the scan directory, we assume it's a Development Environment.
+        // In Dev, we ignore 'dist' to avoid duplicate loading (ts in src vs js in dist).
+        // In Production (no src), we must NOT ignore 'dist', otherwise we can't load compiled hooks/actions.
+        const srcPath = path.join(dir, 'src');
+        const hasSrc = fs.existsSync(srcPath) && fs.statSync(srcPath).isDirectory();
+
+        if (hasSrc) {
+            ignore.push('**/dist/**', '**/build/**', '**/out/**');
+        }
+
+        // 3. User instruction: "src 不行的" (src is not viable for metadata in production)
+        // Metadata (.yml) should ideally be placed in 'objects/' or root, not 'src/', 
+        // to simplify packaging (so you don't need to copy assets from src to dist).
+        // However, we do not strictly block 'src' scanning here to avoid breaking dev workflow.
+        // The exclusion of 'dist' in dev mode (above) handles the code duality.
+
+        const files = glob.sync(plugin.glob, {
+            cwd: dir,
+            absolute: true,
+            ignore
+        });
+
+        for (const file of files) {
+            try {
+                const ctx: LoaderHandlerContext = {
+                    file,
+                    content: '',
+                    registry: this.registry,
+                    packageName
+                };
+                
+                // Pre-read for convenience
+                if (!file.match(/\.(js|ts|node)$/)) {
+                    ctx.content = fs.readFileSync(file, 'utf8');
+                }
+
+                plugin.handler(ctx);
+
+            } catch (e) {
+                console.error(`Error in loader plugin '${plugin.name}' processing ${file}:`, e);
+            }
+        }
+    }
+}
+
+function registerObject(registry: MetadataRegistry, obj: any, file: string, packageName?: string) {
+    if (!obj.name) return;
+
+    // --- Smart Defaults & Normalization ---
+
+    // 1. Object Label: Infer from name if missing
+    if (!obj.label) {
+        obj.label = toTitleCase(obj.name);
+    }
+
+    // 2. Normalize Fields
+    if (obj.fields) {
+        for (const [key, field] of Object.entries(obj.fields)) {
+            if (typeof field === 'object' && field !== null) {
+                const f = field as FieldConfig;
+                
+                // Ensure field has a name
+                if (!f.name) {
+                    f.name = key;
+                }
+
+                // Field Label: Infer from key if missing
+                if (!f.label) {
+                    f.label = toTitleCase(key);
+                }
+
+                // Inferred Types
+                if (!f.type) {
+                    if (f.reference_to) {
+                        f.type = 'lookup';
+                    } else if (f.options) {
+                        f.type = 'select';
+                    } else if (f.formula) {
+                        f.type = 'formula';
+                    } else if (f.summary_object) {
+                        f.type = 'summary';
+                    }
+                }
+            }
+        }
+    }
+
+    // --- End Smart Defaults ---
+
+    // Check for existing object to Merge
+    const existing = registry.getEntry('object', obj.name);
+    if (existing) {
+        const base = existing.content;
+        
+        // Merge Fields: New fields overwrite old ones
+        if (obj.fields) {
+            base.fields = { ...base.fields, ...obj.fields };
+        }
+        
+        // Merge Actions
+        if (obj.actions) {
+            base.actions = { ...base.actions, ...obj.actions };
+        }
+
+        // Merge Indexes
+        if (obj.indexes) {
+            base.indexes = { ...base.indexes, ...obj.indexes };
+        }
+        
+        // Override Top-level Properties if provided
+        if (obj.label) base.label = obj.label;
+        if (obj.icon) base.icon = obj.icon;
+        if (obj.description) base.description = obj.description;
+        if (obj.datasource) base.datasource = obj.datasource;
+        
+        // Update the content reference
+        existing.content = base;
+        return;
+    }
+
+    registry.register('object', {
+        type: 'object',
+        id: obj.name,
+        path: file,
+        package: packageName,
+        content: obj
+    });
+}
+
+export function loadObjectConfigs(dir: string): Record<string, ObjectConfig> {
+    const registry = new MetadataRegistry();
+    const loader = new ObjectLoader(registry);
+    loader.load(dir);
+
+    // Merge actions into objects
+    const actions = registry.list<any>('action');
+    for (const act of actions) {
+        const obj = registry.get<ObjectConfig>('object', act.id);
+        if (obj) {
+            obj.actions = act.content;
+        }
+    }
+
+    const result: Record<string, ObjectConfig> = {};
+    for (const obj of registry.list<ObjectConfig>('object')) {
+        result[obj.name] = obj;
+    }
+    return result;
+}

package/src/plugin.ts

@@ -0,0 +1,53 @@
+import { ObjectQLPlugin } from '@objectql/types';
+
+export function loadPlugin(packageName: string): ObjectQLPlugin {
+    let mod: any;
+    try {
+        const modulePath = require.resolve(packageName, { paths: [process.cwd()] });
+        mod = require(modulePath);
+    } catch (e) {
+        throw new Error(`Failed to resolve plugin '${packageName}': ${e}`);
+    }
+
+    // Helper to find plugin instance
+    const findPlugin = (candidate: any): ObjectQLPlugin | undefined => {
+            if (!candidate) return undefined;
+            
+            // 1. Try treating as Class
+            if (typeof candidate === 'function') {
+                try {
+                    const inst = new candidate();
+                    if (inst && typeof inst.setup === 'function') {
+                        return inst; // Found it!
+                    }
+                } catch (e) {
+                    // Not a constructor or instantiation failed
+                }
+            }
+
+            // 2. Try treating as Instance
+            if (candidate && typeof candidate.setup === 'function') {
+                if (candidate.name) return candidate;
+            }
+            return undefined;
+    };
+
+    // Search in default, module root, and all named exports
+    let instance = findPlugin(mod.default) || findPlugin(mod);
+    
+    if (!instance && mod && typeof mod === 'object') {
+        for (const key of Object.keys(mod)) {
+            if (key === 'default') continue;
+            instance = findPlugin(mod[key]);
+            if (instance) break;
+        }
+    }
+
+    if (instance) {
+        (instance as any)._packageName = packageName;
+        return instance;
+    } else {
+        console.error(`[PluginLoader] Failed to find ObjectQLPlugin in '${packageName}'. Exports:`, Object.keys(mod));
+        throw new Error(`Plugin '${packageName}' must export a class or object implementing ObjectQLPlugin.`);
+    }
+}

package/test/dynamic.test.ts

@@ -0,0 +1,33 @@
+import { ObjectQL } from '@objectql/core';
+import { ObjectLoader } from '../src';
+import * as path from 'path';
+
+describe('Dynamic Package Loading', () => {
+    let objectql: ObjectQL;
+    let loader: ObjectLoader;
+
+    beforeEach(() => {
+        objectql = new ObjectQL({
+            datasources: {}
+        });
+        loader = new ObjectLoader(objectql.metadata);
+    });
+
+    test('should load directory manually', () => {
+        const fixtureDir = path.join(__dirname, 'fixtures');
+        loader.load(fixtureDir, 'test-pkg');
+        
+        expect(objectql.getObject('project')).toBeDefined();
+    });
+
+    test('should remove package objects', () => {
+        const fixtureDir = path.join(__dirname, 'fixtures');
+        loader.load(fixtureDir, 'test-pkg');
+        
+        expect(objectql.getObject('project')).toBeDefined();
+        
+        objectql.removePackage('test-pkg');
+        
+        expect(objectql.getObject('project')).toBeUndefined();
+    });
+});

package/test/fixtures/project-with-validation.object.yml

@@ -0,0 +1,124 @@
+name: project
+label: Project
+description: Project object with validation rules
+
+fields:
+  name:
+    type: text
+    label: Project Name
+    required: true
+    validation:
+      min_length: 3
+      max_length: 100
+      message: Project name must be between 3 and 100 characters
+    ai_context:
+      intent: Unique identifier for the project
+      
+  description:
+    type: textarea
+    label: Description
+    
+  status:
+    type: select
+    label: Status
+    required: true
+    defaultValue: planning
+    options:
+      - label: Planning
+        value: planning
+      - label: Active
+        value: active
+      - label: On Hold
+        value: on_hold
+      - label: Completed
+        value: completed
+      - label: Cancelled
+        value: cancelled
+    ai_context:
+      intent: Track project through its lifecycle
+      is_state_machine: true
+      
+  budget:
+    type: currency
+    label: Budget
+    validation:
+      min: 0
+      max: 10000000
+      message: Budget must be between 0 and 10,000,000
+      
+  start_date:
+    type: date
+    label: Start Date
+    required: true
+    
+  end_date:
+    type: date
+    label: End Date
+    
+  email:
+    type: email
+    label: Contact Email
+    validation:
+      format: email
+      message: Please enter a valid email address
+      
+  website:
+    type: url
+    label: Website
+    validation:
+      format: url
+      protocols: [http, https]
+      message: Please enter a valid URL
+
+validation:
+  ai_context:
+    intent: Ensure project data integrity and enforce business rules
+    validation_strategy: Fail fast with clear error messages
+    
+  rules:
+    # Cross-field validation: End date must be after start date
+    - name: valid_date_range
+      type: cross_field
+      ai_context:
+        intent: Ensure timeline makes logical sense
+        business_rule: Projects cannot end before they start
+        error_impact: high
+      rule:
+        field: end_date
+        operator: ">="
+        compare_to: start_date
+      message: End date must be on or after start date
+      error_code: INVALID_DATE_RANGE
+      
+    # State machine validation
+    - name: status_transition
+      type: state_machine
+      field: status
+      ai_context:
+        intent: Control valid status transitions throughout project lifecycle
+        business_rule: Projects follow a controlled workflow
+      transitions:
+        planning:
+          allowed_next: [active, cancelled]
+          ai_context:
+            rationale: Can start work or cancel before beginning
+        active:
+          allowed_next: [on_hold, completed, cancelled]
+          ai_context:
+            rationale: Can pause, finish, or cancel ongoing work
+        on_hold:
+          allowed_next: [active, cancelled]
+          ai_context:
+            rationale: Can resume or cancel paused projects
+        completed:
+          allowed_next: []
+          is_terminal: true
+          ai_context:
+            rationale: Finished projects cannot change state
+        cancelled:
+          allowed_next: []
+          is_terminal: true
+          ai_context:
+            rationale: Cancelled projects are final
+      message: "Invalid status transition from {{old_status}} to {{new_status}}"
+      error_code: INVALID_STATE_TRANSITION

package/test/fixtures/project.action.js

@@ -0,0 +1,8 @@
+module.exports = {
+    listenTo: 'project',
+    closeProject: {
+        handler: async function(ctx) {
+            return { success: true };
+        }
+    }
+};

package/test/fixtures/project.object.yml

@@ -0,0 +1,41 @@
+name: project
+label: Project
+icon: standard:case
+enable_search: true
+fields:
+  name:
+    label: Project Name
+    type: text
+    required: true
+    searchable: true
+    index: true
+  
+  status:
+    label: Status
+    type: select
+    options:
+      - label: Planned
+        value: planned
+      - label: In Progress
+        value: in_progress
+      - label: Completed
+        value: completed
+    defaultValue: planned
+
+  start_date:
+    label: Start Date
+    type: date
+
+  owner:
+    label: Project Manager
+    type: lookup
+    reference_to: users
+
+  budget:
+    label: Total Budget
+    type: currency
+    scale: 2
+
+  description:
+    label: Description
+    type: textarea