@objectstack/objectql 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @objectstack/objectql
 
+## 0.6.1
+
+### Patch Changes
+
+- Patch release for maintenance and stability improvements
+- Updated dependencies
+  - @objectstack/spec@0.6.1
+  - @objectstack/types@0.6.1
+  - @objectstack/core@0.6.1
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -69,7 +69,8 @@ When building full applications, use the `ObjectKernel` to manage plugins and co
 
 ```typescript
 import { ObjectKernel } from '@objectstack/core';
-import { ObjectQLPlugin, DriverPlugin } from '@objectstack/runtime';
+import { DriverPlugin } from '@objectstack/runtime';
+import { ObjectQLPlugin } from '@objectstack/objectql';
 import { InMemoryDriver } from '@objectstack/driver-memory';
 
 const kernel = new ObjectKernel();

package/dist/engine.d.ts

@@ -0,0 +1,196 @@
+import { HookContext } from '@objectstack/spec/data';
+import { DriverOptions } from '@objectstack/spec/system';
+import { DriverInterface, IDataEngine, DataEngineQueryOptions } from '@objectstack/core';
+export type HookHandler = (context: HookContext) => Promise<void> | void;
+/**
+ * Host Context provided to plugins (Internal ObjectQL Plugin System)
+ */
+export interface ObjectQLHostContext {
+    ql: ObjectQL;
+    logger: Console;
+    [key: string]: any;
+}
+/**
+ * ObjectQL Engine
+ *
+ * Implements the IDataEngine interface for data persistence.
+ */
+export declare class ObjectQL implements IDataEngine {
+    private drivers;
+    private defaultDriver;
+    private hooks;
+    private hostContext;
+    constructor(hostContext?: Record<string, any>);
+    /**
+     * Load and Register a Plugin
+     */
+    use(manifestPart: any, runtimePart?: any): Promise<void>;
+    /**
+     * Register a hook
+     * @param event The event name (e.g. 'beforeFind', 'afterInsert')
+     * @param handler The handler function
+     */
+    registerHook(event: string, handler: HookHandler): void;
+    triggerHooks(event: string, context: HookContext): Promise<void>;
+    registerApp(manifestPart: any): void;
+    /**
+     * Register a new storage driver
+     */
+    registerDriver(driver: DriverInterface, isDefault?: boolean): void;
+    /**
+     * Helper to get object definition
+     */
+    getSchema(objectName: string): {
+        fields: Record<string, {
+            type: "number" | "boolean" | "code" | "date" | "text" | "textarea" | "email" | "url" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "file" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "json" | "color" | "rating" | "slider" | "signature" | "qrcode" | "progress" | "tags" | "vector";
+            required: boolean;
+            searchable: boolean;
+            multiple: boolean;
+            unique: boolean;
+            deleteBehavior: "set_null" | "cascade" | "restrict";
+            hidden: boolean;
+            readonly: boolean;
+            encryption: boolean;
+            index: boolean;
+            externalId: boolean;
+            options?: {
+                value: string;
+                label: string;
+                color?: string | undefined;
+                default?: boolean | undefined;
+            }[] | undefined;
+            min?: number | undefined;
+            max?: number | undefined;
+            formula?: string | undefined;
+            label?: string | undefined;
+            precision?: number | undefined;
+            name?: string | undefined;
+            description?: string | undefined;
+            format?: string | undefined;
+            defaultValue?: any;
+            maxLength?: number | undefined;
+            minLength?: number | undefined;
+            scale?: number | undefined;
+            reference?: string | undefined;
+            referenceFilters?: string[] | undefined;
+            writeRequiresMasterRead?: boolean | undefined;
+            expression?: string | undefined;
+            summaryOperations?: {
+                object: string;
+                function: "count" | "sum" | "avg" | "min" | "max";
+                field: string;
+            } | undefined;
+            language?: string | undefined;
+            theme?: string | undefined;
+            lineNumbers?: boolean | undefined;
+            maxRating?: number | undefined;
+            allowHalf?: boolean | undefined;
+            displayMap?: boolean | undefined;
+            allowGeocoding?: boolean | undefined;
+            addressFormat?: "us" | "uk" | "international" | undefined;
+            colorFormat?: "hex" | "rgb" | "rgba" | "hsl" | undefined;
+            allowAlpha?: boolean | undefined;
+            presetColors?: string[] | undefined;
+            step?: number | undefined;
+            showValue?: boolean | undefined;
+            marks?: Record<string, string> | undefined;
+            barcodeFormat?: "qr" | "ean13" | "ean8" | "code128" | "code39" | "upca" | "upce" | undefined;
+            qrErrorCorrection?: "L" | "M" | "Q" | "H" | undefined;
+            displayValue?: boolean | undefined;
+            allowScanning?: boolean | undefined;
+            currencyConfig?: {
+                precision: number;
+                currencyMode: "dynamic" | "fixed";
+                defaultCurrency: string;
+            } | undefined;
+            vectorConfig?: {
+                dimensions: number;
+                distanceMetric: "cosine" | "euclidean" | "dotProduct" | "manhattan";
+                normalized: boolean;
+                indexed: boolean;
+                indexType?: "flat" | "hnsw" | "ivfflat" | undefined;
+            } | undefined;
+        }>;
+        name: string;
+        active: boolean;
+        isSystem: boolean;
+        abstract: boolean;
+        datasource: string;
+        tags?: string[] | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        search?: {
+            fields: string[];
+            displayFields?: string[] | undefined;
+            filters?: string[] | undefined;
+        } | undefined;
+        pluralLabel?: string | undefined;
+        icon?: string | undefined;
+        tableName?: string | undefined;
+        indexes?: {
+            fields: string[];
+            type?: "hash" | "btree" | "gin" | "gist" | undefined;
+            name?: string | undefined;
+            unique?: boolean | undefined;
+        }[] | undefined;
+        validations?: any[] | undefined;
+        titleFormat?: string | undefined;
+        compactLayout?: string[] | undefined;
+        enable?: {
+            searchable: boolean;
+            trackHistory: boolean;
+            apiEnabled: boolean;
+            files: boolean;
+            feeds: boolean;
+            activities: boolean;
+            trash: boolean;
+            mru: boolean;
+            clone: boolean;
+            apiMethods?: ("update" | "delete" | "get" | "list" | "create" | "upsert" | "bulk" | "aggregate" | "history" | "search" | "restore" | "purge" | "import" | "export")[] | undefined;
+        } | undefined;
+    } | undefined;
+    /**
+     * Helper to get the target driver
+     */
+    private getDriver;
+    /**
+     * Initialize the engine and all registered drivers
+     */
+    init(): Promise<void>;
+    destroy(): Promise<void>;
+    /**
+     * Find records matching a query (IDataEngine interface)
+     *
+     * @param object - Object name
+     * @param query - Query options (IDataEngine format)
+     * @returns Promise resolving to array of records
+     */
+    find(object: string, query?: DataEngineQueryOptions): Promise<any[]>;
+    findOne(object: string, idOrQuery: string | any, options?: DriverOptions): Promise<any>;
+    /**
+     * Insert a new record (IDataEngine interface)
+     *
+     * @param object - Object name
+     * @param data - Data to insert
+     * @returns Promise resolving to the created record
+     */
+    insert(object: string, data: any): Promise<any>;
+    /**
+     * Update a record by ID (IDataEngine interface)
+     *
+     * @param object - Object name
+     * @param id - Record ID
+     * @param data - Updated data
+     * @returns Promise resolving to the updated record
+     */
+    update(object: string, id: any, data: any): Promise<any>;
+    /**
+     * Delete a record by ID (IDataEngine interface)
+     *
+     * @param object - Object name
+     * @param id - Record ID
+     * @returns Promise resolving to true if deleted, false otherwise
+     */
+    delete(object: string, id: any): Promise<boolean>;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}

package/dist/engine.js

@@ -0,0 +1,340 @@
+import { SchemaRegistry } from './registry';
+/**
+ * ObjectQL Engine
+ *
+ * Implements the IDataEngine interface for data persistence.
+ */
+export class ObjectQL {
+    constructor(hostContext = {}) {
+        this.drivers = new Map();
+        this.defaultDriver = null;
+        // Hooks Registry
+        this.hooks = {
+            'beforeFind': [], 'afterFind': [],
+            'beforeInsert': [], 'afterInsert': [],
+            'beforeUpdate': [], 'afterUpdate': [],
+            'beforeDelete': [], 'afterDelete': [],
+        };
+        // Host provided context additions (e.g. Server router)
+        this.hostContext = {};
+        this.hostContext = hostContext;
+        console.log(`[ObjectQL] Engine Instance Created`);
+    }
+    /**
+     * Load and Register a Plugin
+     */
+    async use(manifestPart, runtimePart) {
+        // 1. Validate / Register Manifest
+        if (manifestPart) {
+            this.registerApp(manifestPart);
+        }
+        // 2. Execute Runtime
+        if (runtimePart) {
+            const pluginDef = runtimePart.default || runtimePart;
+            if (pluginDef.onEnable) {
+                const context = {
+                    ql: this,
+                    logger: console,
+                    // Expose the driver registry helper explicitly if needed
+                    drivers: {
+                        register: (driver) => this.registerDriver(driver)
+                    },
+                    ...this.hostContext
+                };
+                await pluginDef.onEnable(context);
+            }
+        }
+    }
+    /**
+     * Register a hook
+     * @param event The event name (e.g. 'beforeFind', 'afterInsert')
+     * @param handler The handler function
+     */
+    registerHook(event, handler) {
+        if (!this.hooks[event]) {
+            this.hooks[event] = [];
+        }
+        this.hooks[event].push(handler);
+        console.log(`[ObjectQL] Registered hook for ${event}`);
+    }
+    async triggerHooks(event, context) {
+        const handlers = this.hooks[event] || [];
+        for (const handler of handlers) {
+            // In a real system, we might want to catch errors here or allow them to bubble up
+            await handler(context);
+        }
+    }
+    registerApp(manifestPart) {
+        // 1. Handle Module Imports (commonjs/esm interop)
+        // If the passed object is a module namespace with a default export, use that.
+        const raw = manifestPart.default || manifestPart;
+        // Support nested manifest property (Stack Definition)
+        // We merge the inner manifest metadata (id, version, etc) with the outer container (objects, apps)
+        const manifest = raw.manifest ? { ...raw, ...raw.manifest } : raw;
+        // In a real scenario, we might strictly parse this using Zod
+        // For now, simple ID check
+        const id = manifest.id || manifest.name;
+        if (!id) {
+            console.warn(`[ObjectQL] Plugin manifest missing ID (keys: ${Object.keys(manifest)})`, manifest);
+            // Don't return, try to proceed if it looks like an App (Apps might use 'name' instead of 'id')
+            // return; 
+        }
+        console.log(`[ObjectQL] Loading App: ${id}`);
+        SchemaRegistry.registerPlugin(manifest);
+        // Register Objects from App/Plugin
+        if (manifest.objects) {
+            for (const obj of manifest.objects) {
+                // Ensure object name is registered globally
+                SchemaRegistry.registerObject(obj);
+                console.log(`[ObjectQL] Registered Object: ${obj.name}`);
+            }
+        }
+        // Register contributions
+        if (manifest.contributes?.kinds) {
+            for (const kind of manifest.contributes.kinds) {
+                SchemaRegistry.registerKind(kind);
+            }
+        }
+    }
+    /**
+     * Register a new storage driver
+     */
+    registerDriver(driver, isDefault = false) {
+        if (this.drivers.has(driver.name)) {
+            console.warn(`[ObjectQL] Driver ${driver.name} is already registered. Skipping.`);
+            return;
+        }
+        this.drivers.set(driver.name, driver);
+        console.log(`[ObjectQL] Registered driver: ${driver.name} v${driver.version}`);
+        if (isDefault || this.drivers.size === 1) {
+            this.defaultDriver = driver.name;
+        }
+    }
+    /**
+     * Helper to get object definition
+     */
+    getSchema(objectName) {
+        return SchemaRegistry.getObject(objectName);
+    }
+    /**
+     * Helper to get the target driver
+     */
+    getDriver(objectName) {
+        const object = SchemaRegistry.getObject(objectName);
+        // 1. If object definition exists, check for explicit datasource
+        if (object) {
+            const datasourceName = object.datasource || 'default';
+            // If configured for 'default', try to find the default driver
+            if (datasourceName === 'default') {
+                if (this.defaultDriver && this.drivers.has(this.defaultDriver)) {
+                    return this.drivers.get(this.defaultDriver);
+                }
+                // Fallback: If 'default' not explicitly set, use the first available driver?
+                // Better to be strict.
+            }
+            else {
+                // Specific datasource requested
+                if (this.drivers.has(datasourceName)) {
+                    return this.drivers.get(datasourceName);
+                }
+                // If not found, fall back to default? Or error?
+                // Standard behavior: Error if specific datasource is missing.
+                throw new Error(`[ObjectQL] Datasource '${datasourceName}' configured for object '${objectName}' is not registered.`);
+            }
+        }
+        // 2. Fallback for ad-hoc objects or missing definitions
+        // If we have a default driver, use it.
+        if (this.defaultDriver) {
+            if (!object) {
+                console.warn(`[ObjectQL] Object '${objectName}' not found in registry. Using default driver.`);
+            }
+            return this.drivers.get(this.defaultDriver);
+        }
+        throw new Error(`[ObjectQL] No driver available for object '${objectName}'`);
+    }
+    /**
+     * Initialize the engine and all registered drivers
+     */
+    async init() {
+        console.log('[ObjectQL] Initializing drivers...');
+        for (const [name, driver] of this.drivers) {
+            try {
+                await driver.connect();
+            }
+            catch (e) {
+                console.error(`[ObjectQL] Failed to connect driver ${name}`, e);
+            }
+        }
+        // In a real app, we would sync schemas here
+    }
+    async destroy() {
+        for (const driver of this.drivers.values()) {
+            await driver.disconnect();
+        }
+    }
+    // ============================================
+    // Data Access Methods (IDataEngine Interface)
+    // ============================================
+    /**
+     * Find records matching a query (IDataEngine interface)
+     *
+     * @param object - Object name
+     * @param query - Query options (IDataEngine format)
+     * @returns Promise resolving to array of records
+     */
+    async find(object, query) {
+        const driver = this.getDriver(object);
+        // Convert DataEngineQueryOptions to QueryAST
+        let ast = { object };
+        if (query) {
+            // Map DataEngineQueryOptions to QueryAST
+            if (query.filter) {
+                ast.where = query.filter;
+            }
+            if (query.select) {
+                ast.fields = query.select;
+            }
+            if (query.sort) {
+                // Convert sort Record to orderBy array
+                // sort: { createdAt: -1, name: 'asc' } => orderBy: [{ field: 'createdAt', order: 'desc' }, { field: 'name', order: 'asc' }]
+                ast.orderBy = Object.entries(query.sort).map(([field, order]) => ({
+                    field,
+                    order: (order === -1 || order === 'desc') ? 'desc' : 'asc'
+                }));
+            }
+            // Handle both limit and top (top takes precedence)
+            if (query.top !== undefined) {
+                ast.limit = query.top;
+            }
+            else if (query.limit !== undefined) {
+                ast.limit = query.limit;
+            }
+            if (query.skip !== undefined) {
+                ast.offset = query.skip;
+            }
+        }
+        // Set default limit if not specified
+        if (ast.limit === undefined)
+            ast.limit = 100;
+        // Trigger Before Hook
+        const hookContext = {
+            object,
+            event: 'beforeFind',
+            input: { ast, options: undefined },
+            ql: this
+        };
+        await this.triggerHooks('beforeFind', hookContext);
+        try {
+            const result = await driver.find(object, hookContext.input.ast, hookContext.input.options);
+            // Trigger After Hook
+            hookContext.event = 'afterFind';
+            hookContext.result = result;
+            await this.triggerHooks('afterFind', hookContext);
+            return hookContext.result;
+        }
+        catch (e) {
+            // hookContext.error = e;
+            throw e;
+        }
+    }
+    async findOne(object, idOrQuery, options) {
+        const driver = this.getDriver(object);
+        let ast;
+        if (typeof idOrQuery === 'string') {
+            ast = {
+                object,
+                where: { _id: idOrQuery }
+            };
+        }
+        else {
+            // Assume query object
+            // reuse logic from find() or just wrap it
+            if (idOrQuery.where || idOrQuery.fields) {
+                ast = { object, ...idOrQuery };
+            }
+            else {
+                ast = { object, where: idOrQuery };
+            }
+        }
+        // Limit 1 for findOne
+        ast.limit = 1;
+        return driver.findOne(object, ast, options);
+    }
+    /**
+     * Insert a new record (IDataEngine interface)
+     *
+     * @param object - Object name
+     * @param data - Data to insert
+     * @returns Promise resolving to the created record
+     */
+    async insert(object, data) {
+        const driver = this.getDriver(object);
+        // 1. Get Schema
+        const schema = SchemaRegistry.getObject(object);
+        if (schema) {
+            // TODO: Validation Logic
+            // validate(schema, data);
+        }
+        // 2. Trigger Before Hook
+        const hookContext = {
+            object,
+            event: 'beforeInsert',
+            input: { data, options: undefined },
+            ql: this
+        };
+        await this.triggerHooks('beforeInsert', hookContext);
+        // 3. Execute Driver
+        const result = await driver.create(object, hookContext.input.data, hookContext.input.options);
+        // 4. Trigger After Hook
+        hookContext.event = 'afterInsert';
+        hookContext.result = result;
+        await this.triggerHooks('afterInsert', hookContext);
+        return hookContext.result;
+    }
+    /**
+     * Update a record by ID (IDataEngine interface)
+     *
+     * @param object - Object name
+     * @param id - Record ID
+     * @param data - Updated data
+     * @returns Promise resolving to the updated record
+     */
+    async update(object, id, data) {
+        const driver = this.getDriver(object);
+        const hookContext = {
+            object,
+            event: 'beforeUpdate',
+            input: { id, data, options: undefined },
+            ql: this
+        };
+        await this.triggerHooks('beforeUpdate', hookContext);
+        const result = await driver.update(object, hookContext.input.id, hookContext.input.data, hookContext.input.options);
+        hookContext.event = 'afterUpdate';
+        hookContext.result = result;
+        await this.triggerHooks('afterUpdate', hookContext);
+        return hookContext.result;
+    }
+    /**
+     * Delete a record by ID (IDataEngine interface)
+     *
+     * @param object - Object name
+     * @param id - Record ID
+     * @returns Promise resolving to true if deleted, false otherwise
+     */
+    async delete(object, id) {
+        const driver = this.getDriver(object);
+        const hookContext = {
+            object,
+            event: 'beforeDelete',
+            input: { id, options: undefined },
+            ql: this
+        };
+        await this.triggerHooks('beforeDelete', hookContext);
+        const result = await driver.delete(object, hookContext.input.id, hookContext.input.options);
+        hookContext.event = 'afterDelete';
+        hookContext.result = result;
+        await this.triggerHooks('afterDelete', hookContext);
+        // Driver.delete() already returns boolean per DriverInterface spec
+        return hookContext.result;
+    }
+}