@objectql/core 1.0.0 → 1.2.0

package/dist/metadata.d.ts

@@ -1,104 +0,0 @@
-/**
- * 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;
-    /**
-     * Options available for `select` or `multiselect` types.
-     * Can be an array of strings or {@link FieldOption} objects.
-     */
-    options?: FieldOption[] | string[];
-    /** Number of decimal places for `currency` types (e.g., 2). */
-    scale?: number;
-    /** Total number of digits for `number` types. */
-    precision?: number;
-    /**
-     * The API name of the target object.
-     * Required when type is `lookup` or `master_detail`.
-     */
-    reference_to?: string;
-    /** 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;
-    /** 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;
-    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;
-    /** Initial data to populate when system starts. */
-    data?: any[];
-}

package/dist/metadata.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":""}

package/dist/query.d.ts

@@ -1,10 +0,0 @@
-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/dist/query.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -1,77 +0,0 @@
-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>;
-    packages?: string[];
-}
-export interface IObjectQL {
-    getObject(name: string): ObjectConfig | undefined;
-    getConfigs(): Record<string, ObjectConfig>;
-    datasource(name: string): Driver;
-    init(): Promise<void>;
-}
-export interface HookContext<T = any> {
-    ctx: ObjectQLContext;
-    entity: string;
-    op: 'find' | 'create' | 'update' | 'delete' | 'count' | 'aggregate';
-    doc?: T;
-    query?: UnifiedQuery;
-    getPreviousDoc: () => Promise<T | undefined>;
-    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 {
-    userId?: string;
-    spaceId?: string;
-    roles: string[];
-    /**
-     * 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;
-    /**
-     * 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/dist/types.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/src/driver.ts

@@ -1,24 +0,0 @@
-export interface Driver {
-    find(objectName: string, query: any, options?: any): Promise<any[]>;
-    findOne(objectName: string, id: string | number, query?: any, options?: any): Promise<any>;
-    create(objectName: string, data: any, options?: any): Promise<any>;
-    update(objectName: string, id: string | number, data: any, options?: any): Promise<any>;
-    delete(objectName: string, id: string | number, options?: any): Promise<any>;
-    count(objectName: string, filters: any, options?: any): Promise<number>;
-    
-    // Advanced
-    aggregate?(objectName: string, query: any, options?: any): Promise<any>;
-    distinct?(objectName: string, field: string, filters?: any, options?: any): Promise<any[]>;
-    
-    // Bulk / Atomic
-    createMany?(objectName: string, data: any[], options?: any): Promise<any>;
-    updateMany?(objectName: string, filters: any, data: any, options?: any): Promise<any>;
-    deleteMany?(objectName: string, filters: any, options?: any): Promise<any>;
-    findOneAndUpdate?(objectName: string, filters: any, update: any, options?: any): Promise<any>;
-
-    // Transaction
-    beginTransaction?(): Promise<any>;
-    commitTransaction?(trx: any): Promise<void>;
-    rollbackTransaction?(trx: any): Promise<void>;
-}
-

package/src/metadata.ts

@@ -1,143 +0,0 @@
-/**
- * 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;
-
-    /** Initial data to populate when system starts. */
-    data?: any[];
-}

package/src/query.ts

@@ -1,11 +0,0 @@
-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/types.ts

@@ -1,109 +0,0 @@
-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>;
-    packages?: string[];
-}
-
-export interface IObjectQL {
-    getObject(name: string): ObjectConfig | undefined;
-    getConfigs(): Record<string, ObjectConfig>;
-    datasource(name: string): Driver;
-    init(): Promise<void>;
-}
-
-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.action.ts

@@ -1,6 +0,0 @@
-// Fixture for testing action loader
-export const listenTo = 'project';
-
-export async function closeProject(ctx: any, params: any) {
-    return { success: true };
-}

package/test/fixtures/project.object.yml

@@ -1,41 +0,0 @@
-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

@@ -1,22 +0,0 @@
-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();
-    });
-
-    it('should load actions from .action.ts files', () => {
-        const fixturesDir = path.join(__dirname, 'fixtures');
-        const configs = loadObjectConfigs(fixturesDir);
-        expect(configs['project'].actions).toBeDefined();
-        expect(configs['project'].actions!.closeProject).toBeDefined();
-        expect(typeof configs['project'].actions!.closeProject.handler).toBe('function');
-    });
-});

package/test/metadata.test.ts

@@ -1,49 +0,0 @@
-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();
-    });
-});