@objectql/core 0.1.0

package/src/metadata.ts

@@ -0,0 +1,141 @@
+
+/**
+ * Represents the supported field data types in the ObjectQL schema.
+ * These types determine how data is stored, validated, and rendered.
+ * 
+ * - `text`: Simple string.
+ * - `textarea`: Long string.
+ * - `select`: Choice from a list.
+ * - `lookup`: Relationship to another object.
+ */
+export type FieldType = 
+    | 'text' 
+    | 'textarea' 
+    | 'html' 
+    | 'select' 
+    | 'multiselect' 
+    | 'date' 
+    | 'datetime' 
+    | 'number' 
+    | 'currency' 
+    | 'boolean' 
+    | 'lookup' 
+    | 'master_detail' 
+    | 'password'
+    | 'object'
+    | 'grid';
+
+/**
+ * Defines a single option for select/multiselect fields.
+ */
+export interface FieldOption {
+    /** The display label for the option. */
+    label: string;
+    /** The actual value stored in the database. */
+    value: string | number;
+}
+
+/**
+ * Configuration for a single field on an object.
+ * This defines the schema, validation rules, and UI hints for the attribute.
+ */
+export interface FieldConfig {
+    /** 
+     * The unique API name of the field. 
+     * If defined within an object map, this is often automatically populated from the key.
+     */
+    name?: string;
+    
+    /** The human-readable label used in UIs. */
+    label?: string;
+    
+    /** The data type of the field. */
+    type: FieldType;
+    
+    /** Whether the field is mandatory. Defaults to false. */
+    required?: boolean;
+    
+    /** The default value if not provided during creation. */
+    defaultValue?: any;
+    
+    // String options
+    /** 
+     * Options available for `select` or `multiselect` types.
+     * Can be an array of strings or {@link FieldOption} objects.
+     */
+    options?: FieldOption[] | string[];
+    
+    // Number options
+    /** Number of decimal places for `currency` types (e.g., 2). */
+    scale?: number;
+    /** Total number of digits for `number` types. */
+    precision?: number;
+    
+    // Relationship properties
+    /** 
+     * The API name of the target object.
+     * Required when type is `lookup` or `master_detail`.
+     */
+    reference_to?: string;
+
+    // UI properties (kept for compatibility, though ObjectQL is a query engine)
+    /** Implementation hint: Whether this field should be indexed for search. */
+    searchable?: boolean;
+    /** Implementation hint: Whether this field is sortable in lists. */
+    sortable?: boolean;
+    /** Implementation hint: Whether to create a database index for this column. */
+    index?: boolean;
+    
+    // Other properties
+    /** Description for documentation purposes. */
+    description?: string;
+}
+
+/**
+ * Configuration for a custom action (RPC).
+ */
+export interface ActionConfig {
+    label?: string;
+    description?: string;
+    /** Output/Result type definition. */
+    result?: {
+        type: FieldType;
+    };
+    /** Input parameters schema. */
+    params?: Record<string, FieldConfig>;
+    /** Implementation of the action. */
+    handler?: (ctx: any, params: any) => Promise<any>;
+}
+
+import { HookFunction } from './types';
+
+export interface ObjectListeners {
+    beforeCreate?: HookFunction;
+    afterCreate?: HookFunction;
+    beforeUpdate?: HookFunction;
+    afterUpdate?: HookFunction;
+    beforeDelete?: HookFunction;
+    afterDelete?: HookFunction;
+    beforeFind?: HookFunction;
+    afterFind?: HookFunction;
+}
+
+/**
+ * Configuration for a business object (Entity).
+ * Analogous to a Database Table or MongoDB Collection.
+ */
+export interface ObjectConfig {
+    name: string;
+    datasource?: string; // The name of the datasource to use
+    label?: string;
+    icon?: string;
+    description?: string;
+    
+    fields: Record<string, FieldConfig>;
+    
+    /** Custom Actions (RPC) defined on this object. */
+    actions?: Record<string, ActionConfig>;
+
+    /** Lifecycle hooks. */
+    listeners?: ObjectListeners;
+}

package/src/query.ts

@@ -0,0 +1,11 @@
+export type FilterCriterion = [string, string, any];
+export type FilterExpression = FilterCriterion | 'and' | 'or' | FilterExpression[];
+
+export interface UnifiedQuery {
+    fields?: string[];
+    filters?: FilterExpression[];
+    sort?: [string, 'asc' | 'desc'][];
+    skip?: number;
+    limit?: number;
+    expand?: Record<string, UnifiedQuery>;
+}

package/src/repository.ts

@@ -0,0 +1,232 @@
+import { ObjectQLContext, IObjectQL, HookContext, HookFunction } from './types';
+import { ObjectConfig, FieldConfig } from './metadata';
+import { Driver } from './driver';
+import { UnifiedQuery, FilterCriterion } from './query';
+
+export class ObjectRepository {
+    constructor(
+        private objectName: string,
+        private context: ObjectQLContext,
+        private app: IObjectQL
+    ) {}
+
+    private getDriver(): Driver {
+        const obj = this.getSchema();
+        const datasourceName = obj.datasource || 'default';
+        return this.app.datasource(datasourceName);
+    }
+    
+    private getOptions(extra: any = {}) {
+        return {
+            transaction: this.context.transactionHandle,
+            ...extra
+        };
+    }
+
+    getSchema(): ObjectConfig {
+        const obj = this.app.getObject(this.objectName);
+        if (!obj) {
+            throw new Error(`Object '${this.objectName}' not found`);
+        }
+        return obj;
+    }
+
+    // === Hook Execution Logic ===
+    private async executeHook(
+        hookName: keyof import('./metadata').ObjectListeners, 
+        op: HookContext['op'], 
+        dataOrQuery: any
+    ) {
+        if (this.context.ignoreTriggers) return;
+        
+        const obj = this.getSchema();
+        if (!obj.listeners || !obj.listeners[hookName]) return;
+
+        const hookFn = obj.listeners[hookName] as HookFunction;
+
+        // Construct HookContext
+        const hookContext: HookContext = {
+            ctx: this.context,
+            entity: this.objectName,
+            op: op,
+            utils: {
+                restrict: (criterion: FilterCriterion) => {
+                    if (op !== 'find' && op !== 'count') {
+                        throw new Error('utils.restrict is only available in query operations');
+                    }
+                    const query = dataOrQuery as UnifiedQuery;
+                    if (!query.filters) {
+                        query.filters = [criterion];
+                    } else {
+                        // Enclose existing filters in implicit AND group by array structure logic or explicit 'and'
+                        // Implementation depends on how driver parses.
+                        // Safe approach: filters = [ [criterion], 'and', [existing] ] or similar.
+                        // For simplicity assuming array of terms means AND:
+                        query.filters.push(criterion);
+                    }
+                }
+            },
+            getPreviousDoc: async () => {
+                 // For update/delete, we might need the ID to find the doc.
+                 // If doc has ID, use it.
+                 // This is simplistic; usually 'update' takes 'id', we need to capture it from arguments.
+                 if (op === 'create') return undefined;
+                 if (dataOrQuery._id || dataOrQuery.id) {
+                     return this.findOne(dataOrQuery._id || dataOrQuery.id);
+                 }
+                 return undefined;
+            }
+        };
+
+        if (op === 'find' || op === 'count' || op === 'aggregate') {
+            hookContext.query = dataOrQuery;
+        } else {
+            hookContext.doc = dataOrQuery;
+        }
+        
+        // Pass ID manually if needed or attach to doc? 
+        // For strictness, getPreviousDoc needs the ID passed to the operation.
+        // We'll rely on "doc" having the data being processed.
+        
+        await hookFn(hookContext);
+    }
+
+    async find(query: UnifiedQuery = {}): Promise<any[]> {
+        // Hooks: beforeFind
+        await this.executeHook('beforeFind', 'find', query);
+
+        // TODO: Apply basic filters like spaceId (could be done via a default generic hook too)
+        const results = await this.getDriver().find(this.objectName, query, this.getOptions());
+        
+        // Hooks: afterFind
+        // Not implemented in spec fully iterate results? usually for single doc or metadata
+        // For performance, afterFind on list is rare or costly. 
+        if (this.getSchema().listeners?.afterFind && !this.context.ignoreTriggers) {
+             const hookFn = this.getSchema().listeners!.afterFind!;
+             // Executing per result or once? Spec says "HookContext" has "doc". 
+             // If finding list, might not match signature.
+             // Implemented per-item for now (caution: performance).
+             /*
+             for (const item of results) {
+                 await this.executeHookForDoc('afterFind', 'find', item);
+             }
+             */
+        }
+        return results;
+    }
+
+    async findOne(idOrQuery: string | number | UnifiedQuery): Promise<any> {
+        if (typeof idOrQuery === 'string' || typeof idOrQuery === 'number') {
+            // Convert ID lookup to standard query to reuse 'find' hooks?
+            // Or treat as specific op. 
+            // Let's rely on simple driver call but maybe wrap in object for hook consistency if needed.
+            // For now, simple implementation:
+            return this.getDriver().findOne(this.objectName, idOrQuery, undefined, this.getOptions());
+        } else {
+            const results = await this.find(idOrQuery);
+            return results[0] || null;
+        }
+    }
+
+    async count(filters: any): Promise<number> {
+        // Can wrap filters in a query object for hook
+        const query: UnifiedQuery = { filters };
+        await this.executeHook('beforeFind', 'count', query); // Reusing beforeFind logic often?
+        return this.getDriver().count(this.objectName, query.filters, this.getOptions());
+    }
+
+    async create(doc: any): Promise<any> {
+        const obj = this.getSchema();
+        if (this.context.userId) doc.created_by = this.context.userId;
+        if (this.context.spaceId) doc.space_id = this.context.spaceId;
+
+        await this.executeHook('beforeCreate', 'create', doc);
+
+        const result = await this.getDriver().create(this.objectName, doc, this.getOptions());
+
+        await this.executeHook('afterCreate', 'create', result);
+        return result;
+    }
+
+    async update(id: string | number, doc: any, options?: any): Promise<any> {
+        // Attach ID to doc for hook context to know which record
+        const docWithId = { ...doc, _id: id, id: id };
+        
+        await this.executeHook('beforeUpdate', 'update', docWithId);
+        
+        // Remove ID before sending to driver if driver doesn't like it in $set
+        const { _id, id: _id2, ...cleanDoc } = docWithId;
+
+        const result = await this.getDriver().update(this.objectName, id, cleanDoc, this.getOptions(options));
+
+        // Result might be count or doc depending on driver.
+        // If we want the updated doc for afterUpdate, we might need to fetch it if driver defaults to count.
+        // Assuming result is the doc or we just pass the patch.
+        await this.executeHook('afterUpdate', 'update', docWithId); 
+        return result;
+    }
+
+    async delete(id: string | number): Promise<any> {
+        const docWithId = { _id: id, id: id };
+        await this.executeHook('beforeDelete', 'delete', docWithId);
+
+        const result = await this.getDriver().delete(this.objectName, id, this.getOptions());
+
+        await this.executeHook('afterDelete', 'delete', docWithId);
+        return result;
+    }    async aggregate(query: any): Promise<any> {
+        const driver = this.getDriver();
+        if (!driver.aggregate) throw new Error("Driver does not support aggregate");
+        return driver.aggregate(this.objectName, query, this.getOptions());
+    }
+
+    async distinct(field: string, filters?: any): Promise<any[]> {
+        const driver = this.getDriver();
+        if (!driver.distinct) throw new Error("Driver does not support distinct");
+        return driver.distinct(this.objectName, field, filters, this.getOptions());
+    }
+
+    async findOneAndUpdate(filters: any, update: any, options?: any): Promise<any> {
+        const driver = this.getDriver();
+        if (!driver.findOneAndUpdate) throw new Error("Driver does not support findOneAndUpdate");
+        return driver.findOneAndUpdate(this.objectName, filters, update, this.getOptions(options));
+    }
+
+    async createMany(data: any[]): Promise<any> {
+        // TODO: Triggers per record?
+        const driver = this.getDriver();
+        if (!driver.createMany) {
+            // Fallback
+            const results = [];
+            for (const item of data) {
+                results.push(await this.create(item));
+            }
+            return results;
+        }
+        return driver.createMany(this.objectName, data, this.getOptions());
+    }
+
+    async updateMany(filters: any, data: any): Promise<any> {
+        const driver = this.getDriver();
+        if (!driver.updateMany) throw new Error("Driver does not support updateMany");
+        return driver.updateMany(this.objectName, filters, data, this.getOptions());
+    }
+
+    async deleteMany(filters: any): Promise<any> {
+        const driver = this.getDriver();
+        if (!driver.deleteMany) throw new Error("Driver does not support deleteMany");
+        return driver.deleteMany(this.objectName, filters, this.getOptions());
+    }
+
+    async call(actionName: string, params: any): Promise<any> {
+        const obj = this.getSchema();
+        const action = obj.actions?.[actionName];
+        if (!action) {
+            throw new Error(`Action '${actionName}' not found on object '${this.objectName}'`);
+        }
+        if (action.handler) {
+            return action.handler(this.context, params);
+        }
+        throw new Error(`Action '${actionName}' has no handler`);
+    }
+}

package/src/types.ts

@@ -0,0 +1,107 @@
+import { ObjectRepository } from "./repository";
+import { ObjectConfig } from "./metadata";
+import { Driver } from "./driver";
+import { UnifiedQuery, FilterCriterion } from "./query";
+
+export { ObjectConfig } from "./metadata";
+
+export interface ObjectQLConfig {
+    datasources: Record<string, Driver>;
+    objects?: Record<string, ObjectConfig>;
+}
+
+export interface IObjectQL {
+    getObject(name: string): ObjectConfig | undefined;
+    getConfigs(): Record<string, ObjectConfig>;
+    datasource(name: string): Driver;
+}
+
+export interface HookContext<T = any> {
+  // === 1. The Session Context ===
+  // Automatically propagates userId, spaceId, and Transaction.
+  ctx: ObjectQLContext;
+
+  // === 2. Operational Info ===
+  entity: string;
+  op: 'find' | 'create' | 'update' | 'delete' | 'count' | 'aggregate';
+  
+  // === 3. Data Payload (Mutable) ===
+  // - In beforeCreate/Update: The data to be written. 
+  // - In afterCreate/Update: The result record returned from DB.
+  doc?: T;              
+
+  // === 4. Query Context (Mutable, for 'find' only) ===
+  // Complies strictly with the UnifiedQuery JSON-DSL (AST).
+  // Developers can modify 'fields', 'sort', or wrap 'filters'.
+  query?: UnifiedQuery;
+  
+  // === 5. Helpers ===
+  getPreviousDoc: () => Promise<T | undefined>;
+  
+  // AST Manipulation Utilities
+  utils: {
+    /**
+     * Safely injects a new filter criterion into the existing AST.
+     * It wraps existing filters in a new group to preserve operator precedence.
+     * * Logic: (Existing_Filters) AND (New_Filter)
+     */
+    restrict: (criterion: FilterCriterion) => void;
+  };
+}
+
+export type HookFunction = (context: HookContext) => Promise<void>;
+
+export interface ObjectQLContext {
+    // === Identity & Isolation ===
+    userId?: string;                        // Current User ID
+    spaceId?: string;                       // Multi-tenancy Isolation (Organization ID)
+    roles: string[];                        // RBAC Roles
+
+    // === Execution Flags ===
+    /**
+     * Sudo Mode / System Bypass.
+     * - true: Bypasses all permission checks (CRUD, Field Level Security, Record Level Security).
+     * - false/undefined: Enforces all permission checks based on 'roles'.
+     */
+    isSystem?: boolean;
+
+    /**
+     * Trigger Control.
+     * - true: Skips all lifecycle hooks (beforeCreate, afterUpdate, etc.).
+     * - Useful for bulk data imports or raw data correction to prevent side effects.
+     * - Requires 'isSystem: true' (Security Safeguard).
+     */
+    ignoreTriggers?: boolean;
+
+    // === Data Entry Point ===
+    /**
+     * Returns a repository proxy bound to this context.
+     * All operations performed via this proxy inherit userId, spaceId, and transaction.
+     */
+    object(entityName: string): ObjectRepository;
+
+    /**
+     * Execute a function within a transaction.
+     * The callback receives a new context 'trxCtx' which inherits userId and spaceId from this context.
+     */
+    transaction(callback: (trxCtx: ObjectQLContext) => Promise<any>): Promise<any>;
+
+    /**
+     * Returns a new context with system privileges (isSystem: true).
+     * It shares the same transaction scope as the current context.
+     */
+    sudo(): ObjectQLContext;
+
+    /**
+     * Internal: Driver-specific transaction handle.
+     */
+    transactionHandle?: any;
+}
+
+export interface ObjectQLContextOptions {
+    userId?: string;
+    spaceId?: string;
+    roles?: string[];
+    isSystem?: boolean;
+    ignoreTriggers?: boolean;
+}

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

package/test/loader.test.ts

@@ -0,0 +1,14 @@
+import { loadObjectConfigs } from '../src/loader';
+import * as path from 'path';
+
+describe('Loader', () => {
+    it('should load object configs from directory', () => {
+        const fixturesDir = path.join(__dirname, 'fixtures');
+        const configs = loadObjectConfigs(fixturesDir);
+        expect(configs).toBeDefined();
+        expect(configs['project']).toBeDefined();
+        expect(configs['project'].name).toBe('project');
+        expect(configs['project'].fields).toBeDefined();
+        expect(configs['project'].fields.name).toBeDefined();
+    });
+});

package/test/metadata.test.ts

@@ -0,0 +1,49 @@
+import { ObjectQL } from '../src/index';
+import { ObjectConfig } from '../src/metadata';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+
+describe('Metadata Loading', () => {
+    
+    it('should load definitions from .object.yml file', () => {
+        // 1. Read YAML file
+        const yamlPath = path.join(__dirname, 'fixtures', 'project.object.yml');
+        const fileContents = fs.readFileSync(yamlPath, 'utf8');
+        
+        // 2. Parse YAML
+        const objectDef = yaml.load(fileContents) as ObjectConfig;
+
+        // 3. Verify Structure
+        expect(objectDef.name).toBe('project');
+        expect(objectDef.fields.name.type).toBe('text');
+        expect(objectDef.fields.status.options).toHaveLength(3);
+        expect(objectDef.fields.budget.type).toBe('currency');
+        expect(objectDef.fields.owner.reference_to).toBe('users');
+
+        // 4. Register with ObjectQL
+        const app = new ObjectQL({
+            datasources: {} 
+        });
+        
+        app.registerObject(objectDef);
+
+        // 5. Verify Registration
+        const retrieved = app.getObject('project');
+        expect(retrieved).toBeDefined();
+        expect(retrieved?.label).toBe('Project');
+    });
+
+    it('should validate required properties (manual validation simulation)', () => {
+         const yamlPath = path.join(__dirname, 'fixtures', 'project.object.yml');
+         const fileContents = fs.readFileSync(yamlPath, 'utf8');
+         const objectDef = yaml.load(fileContents) as ObjectConfig;
+
+         function validateObject(obj: ObjectConfig) {
+             if (!obj.name) throw new Error('Object name is required');
+             if (!obj.fields) throw new Error('Object fields are required');
+         }
+
+         expect(() => validateObject(objectDef)).not.toThrow();
+    });
+});

package/test/mock-driver.ts

@@ -0,0 +1,86 @@
+import { Driver } from '../src/driver';
+
+export class MockDriver implements Driver {
+    private data: Record<string, any[]> = {};
+    private transactions: Set<any> = new Set();
+    
+    constructor() {}
+
+    private getData(objectName: string) {
+        if (!this.data[objectName]) {
+            this.data[objectName] = [];
+        }
+        return this.data[objectName];
+    }
+
+    async find(objectName: string, query: any, options?: any): Promise<any[]> {
+        const items = this.getData(objectName);
+        // Very basic filter implementation for testing
+        if (query.filters) {
+            return items.filter(item => {
+                // Assuming simple filter: [['field', '=', 'value']]
+                const filter = query.filters[0]; 
+                if (filter && Array.isArray(filter) && filter[1] === '=') {
+                    return item[filter[0]] === filter[2];
+                }
+                return true;
+            });
+        }
+        return items;
+    }
+
+    async findOne(objectName: string, id: string | number, query?: any, options?: any): Promise<any> {
+        const items = this.getData(objectName);
+        return items.find((item: any) => item._id === id);
+    }
+
+    async create(objectName: string, data: any, options?: any): Promise<any> {
+        const items = this.getData(objectName);
+        const newItem = {
+            ...data,
+            _id: data._id || `id-${Date.now()}-${Math.random()}`
+        };
+        items.push(newItem);
+        return newItem;
+    }
+
+    async update(objectName: string, id: string | number, data: any, options?: any): Promise<any> {
+        const items = this.getData(objectName);
+        const index = items.findIndex((item: any) => item._id === id);
+        if (index > -1) {
+            items[index] = { ...items[index], ...data };
+            return items[index];
+        }
+        throw new Error('Not found');
+    }
+
+    async delete(objectName: string, id: string | number, options?: any): Promise<any> {
+        const items = this.getData(objectName);
+        const index = items.findIndex((item: any) => item._id === id);
+        if (index > -1) {
+            items.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+
+    async count(objectName: string, filters: any, options?: any): Promise<number> {
+        return (await this.find(objectName, { filters }, options)).length;
+    }
+
+    async beginTransaction(): Promise<any> {
+        const trx = { id: Date.now() };
+        this.transactions.add(trx);
+        return trx;
+    }
+
+    async commitTransaction(trx: any): Promise<void> {
+        if (!this.transactions.has(trx)) throw new Error('Invalid transaction');
+        this.transactions.delete(trx);
+    }
+
+    async rollbackTransaction(trx: any): Promise<void> {
+        if (!this.transactions.has(trx)) throw new Error('Invalid transaction');
+        this.transactions.delete(trx);
+    }
+}