@objectql/core 1.1.0 → 1.3.0

package/README.md

@@ -1,53 +0,0 @@
-# @objectql/core
-
-The core ORM and runtime engine for ObjectQL. This package handles object querying, CRUD operations, database driver coordination, and transaction management.
-
-## Features
-
-- **Unified Query Language**: A generic way to query data across different databases (SQL, Mongo, etc.).
-- **Repository Pattern**: `ObjectRepository` for managing object records.
-- **Driver Agnostic**: Abstraction layer for database drivers.
-- **Dynamic Schema**: Loads object definitions from `@objectql/metadata`.
-- **Hooks & Actions**: Runtime logic injection.
-
-## Installation
-
-```bash
-npm install @objectql/core
-```
-
-## Usage
-
-```typescript
-import { ObjectQL } from '@objectql/core';
-import { MetadataRegistry } from '@objectql/metadata';
-// Import a driver, e.g., @objectql/driver-knex
-
-const objectql = new ObjectQL({
-    datasources: {
-        default: new MyDriver({ ... })
-    }
-});
-
-await objectql.init();
-
-// Use context for operations
-const ctx = objectql.createContext({ userId: 'u-1' });
-const projects = await ctx.object('project').find({
-    filters: [['status', '=', 'active']]
-});
-```
-
-## Shared Metadata
-
-You can pass an existing `MetadataRegistry` (e.g., from a low-code platform loader) to ObjectQL:
-
-```typescript
-const registry = new MetadataRegistry();
-// ... pre-load metadata ...
-
-const objectql = new ObjectQL({
-    registry: registry,
-    datasources: { ... }
-});
-```

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/registry.d.ts

@@ -1,4 +0,0 @@
-import { MetadataRegistry as BaseRegistry, Metadata } from '@objectql/metadata';
-export { Metadata };
-export declare class MetadataRegistry extends BaseRegistry {
-}

package/dist/registry.js

@@ -1,8 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MetadataRegistry = void 0;
-const metadata_1 = require("@objectql/metadata");
-class MetadataRegistry extends metadata_1.MetadataRegistry {
-}
-exports.MetadataRegistry = MetadataRegistry;
-//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":";;;AAAA,iDAAgF;AAGhF,MAAa,gBAAiB,SAAQ,2BAAY;CAEjD;AAFD,4CAEC"}

package/dist/types.d.ts

@@ -1,83 +0,0 @@
-import { ObjectRepository } from "./repository";
-import { ObjectConfig } from "./metadata";
-import { Driver } from "./driver";
-import { UnifiedQuery, FilterCriterion } from "./query";
-import { MetadataRegistry } from "./registry";
-export { ObjectConfig } from "./metadata";
-export { MetadataRegistry } from "./registry";
-export interface ObjectQLConfig {
-    registry?: MetadataRegistry;
-    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>;
-    addPackage(name: string): void;
-    removePackage(name: string): void;
-    metadata: MetadataRegistry;
-}
-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,6 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MetadataRegistry = void 0;
-var registry_1 = require("./registry");
-Object.defineProperty(exports, "MetadataRegistry", { enumerable: true, get: function () { return registry_1.MetadataRegistry; } });
-//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAOA,uCAA8C;AAArC,4GAAA,gBAAgB,OAAA"}

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/registry.ts

@@ -1,6 +0,0 @@
-import { MetadataRegistry as BaseRegistry, Metadata } from '@objectql/metadata';
-
-export { Metadata };
-export class MetadataRegistry extends BaseRegistry {
-    // Re-export or extend if needed
-}

package/src/types.ts

@@ -1,115 +0,0 @@
-import { ObjectRepository } from "./repository";
-import { ObjectConfig } from "./metadata";
-import { Driver } from "./driver";
-import { UnifiedQuery, FilterCriterion } from "./query";
-import { MetadataRegistry } from "./registry";
-
-export { ObjectConfig } from "./metadata";
-export { MetadataRegistry } from "./registry";
-
-export interface ObjectQLConfig {
-    registry?: MetadataRegistry;
-    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>;
-    addPackage(name: string): void;
-    removePackage(name: string): void;
-    metadata: MetadataRegistry; 
-}
-
-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 };
-}