@objectql/types 1.2.0

package/dist/types.d.ts

@@ -0,0 +1,103 @@
+import { ObjectConfig } from "./object";
+import { Driver } from "./driver";
+import { UnifiedQuery } from "./query";
+import { ObjectRegistry } from "./registry";
+import { HookName, HookHandler, HookContext } from "./hook";
+import { ActionHandler, ActionContext } from "./action";
+export { ObjectConfig } from "./object";
+export { ObjectRegistry } from "./registry";
+export * from "./hook";
+export * from "./action";
+export interface IObjectRepository {
+    find(query?: UnifiedQuery): Promise<any[]>;
+    findOne(idOrQuery: string | number | UnifiedQuery): Promise<any>;
+    count(filters: any): Promise<number>;
+    create(doc: any): Promise<any>;
+    update(id: string | number, doc: any, options?: any): Promise<any>;
+    delete(id: string | number): Promise<any>;
+    aggregate(query: any): Promise<any>;
+    distinct(field: string, filters?: any): Promise<any[]>;
+    findOneAndUpdate?(filters: any, update: any, options?: any): Promise<any>;
+    createMany(data: any[]): Promise<any>;
+    updateMany(filters: any, data: any): Promise<any>;
+    deleteMany(filters: any): Promise<any>;
+    execute(actionName: string, id: string | number | undefined, params: any): Promise<any>;
+}
+export interface ObjectQLPlugin {
+    name: string;
+    setup(app: IObjectQL): void | Promise<void>;
+}
+export interface ObjectQLConfig {
+    registry?: ObjectRegistry;
+    datasources?: Record<string, Driver>;
+    /**
+     * Optional connection string for auto-configuration.
+     * e.g. "sqlite://dev.db", "postgres://localhost/db", "mongodb://localhost/db"
+     */
+    connection?: string;
+    /**
+     * Path(s) to the directory containing schema files (*.object.yml).
+     */
+    source?: string | string[];
+    objects?: Record<string, ObjectConfig>;
+    /**
+     * @deprecated Use 'presets' instead.
+     */
+    packages?: string[];
+    /**
+     * List of npm packages or presets to load.
+     */
+    presets?: string[];
+    /**
+     * List of plugins to load.
+     * Can be an instance of ObjectQLPlugin or a package name string.
+     */
+    plugins?: (ObjectQLPlugin | 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: ObjectRegistry;
+    on(event: HookName, objectName: string, handler: HookHandler): void;
+    triggerHook(event: HookName, objectName: string, ctx: HookContext): Promise<void>;
+    registerAction(objectName: string, actionName: string, handler: ActionHandler): void;
+    executeAction(objectName: string, actionName: string, ctx: ActionContext): Promise<any>;
+}
+export interface ObjectQLContext {
+    userId?: string;
+    spaceId?: string;
+    roles: string[];
+    /**
+     * Sudo Mode / System Bypass.
+     */
+    isSystem?: boolean;
+    /**
+     * Returns a repository proxy bound to this context.
+     * All operations performed via this proxy inherit userId, spaceId, and transaction.
+     */
+    object(entityName: string): IObjectRepository;
+    /**
+     * Execute a function within a transaction.
+     * The callback receives a new context 'trxCtx' which inherits userId, 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;
+}

package/dist/types.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObjectRegistry = void 0;
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "ObjectRegistry", { enumerable: true, get: function () { return registry_1.ObjectRegistry; } });
+__exportStar(require("./hook"), exports);
+__exportStar(require("./action"), exports);
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAQA,uCAA4C;AAAnC,0GAAA,cAAc,OAAA;AACvB,yCAAuB;AACvB,2CAAyB"}

package/jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/test/**/*.test.ts'],
+};

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@objectql/types",
+  "version": "1.2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {},
+  "scripts": {
+    "build": "tsc",
+    "test": "jest"
+  }
+}

package/src/action.ts

@@ -0,0 +1,96 @@
+import { FieldConfig } from "./field";
+import { HookAPI } from "./hook"; // Reuse the restricted API interface
+
+/**
+ * Defines the scope of the action.
+ * - `record`: Acts on a specific record instance (e.g. "Approve Order").
+ * - `global`: Acts on the collection or system (e.g. "Import CSV", "Daily Report").
+ */
+export type ActionType = 'record' | 'global';
+
+/**
+ * Re-using FieldConfig allows us to describe input parameters 
+ * using the same rich vocabulary as database fields (validation, UI hints, etc).
+ */
+export type ActionInputDefinition = Record<string, FieldConfig>;
+
+/**
+ * Context passed to the action handler execution.
+ */
+export interface ActionContext<BaseT = any, InputT = any> {
+    /** The object this action belongs to. */
+    objectName: string;
+    
+    /** The name of the action being executed. */
+    actionName: string;
+
+    /** 
+     * The ID of the record being acted upon.
+     * Only available if type is 'record'.
+     */
+    id?: string | number;
+
+    /**
+     * The validated input arguments.
+     */
+    input: InputT;
+
+    /**
+     * Database Access API (Same as Hooks).
+     */
+    api: HookAPI;
+
+    /**
+     * User Session.
+     */
+    user?: {
+        id: string | number;
+        [key: string]: any;
+    };
+}
+
+/**
+ * The configuration of an Action visible to the Metadata engine (YAML/JSON side).
+ */
+export interface ActionConfig {
+    label?: string;
+    description?: string;
+    icon?: string;
+    
+    /**
+     * Default: 'global' if no fields defined, but usually specified explicitly.
+     */
+    type?: ActionType; // 'record' | 'global'
+
+    /**
+     * Message to show before executing. If present, UI should prompt confirmation.
+     */
+    confirm_text?: string;
+    
+    /**
+     * If true, this action is not exposed via API directly (server-internal).
+     */
+    internal?: boolean;
+    
+    /**
+     * Input parameter schema.
+     */
+    params?: ActionInputDefinition;
+    
+    /**
+     * Output data shape description (optional, for content negotiation).
+     */
+    return_type?: string | FieldConfig; 
+}
+
+/**
+ * The full implementation definition (Code side).
+ */
+export interface ActionDefinition<BaseT = any, InputT = any, ReturnT = any> extends ActionConfig {
+    /**
+     * The business logic implementation.
+     */
+    handler: (ctx: ActionContext<BaseT, InputT>) => Promise<ReturnT>;
+}
+
+export type ActionHandler<BaseT = any, InputT = any, ReturnT = any> = (ctx: ActionContext<BaseT, InputT>) => Promise<ReturnT>;

package/src/driver.ts

@@ -0,0 +1,27 @@
+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>;
+    
+    // Schema / Lifecycle
+    init?(objects: any[]): Promise<void>;
+
+    // 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/field.ts

@@ -0,0 +1,124 @@
+/**
+ * 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' 
+    | 'markdown'
+    | 'html' 
+    | 'select' 
+    | 'date' 
+    | 'datetime' 
+    | 'time'
+    | 'number' 
+    | 'currency' 
+    | 'percent'
+    | 'boolean' 
+    | 'email'
+    | 'phone'
+    | 'url'
+    | 'image'
+    | 'file'
+    | 'avatar'
+    | 'location'
+    | 'lookup' 
+    | 'master_detail'  
+    | 'password'
+    | 'formula'
+    | 'summary'
+    | 'auto_number'
+    | 'object'
+    | 'vector'
+    | '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;
+
+    /** Description of the field for documentation or tooltip. */
+    description?: string;
+    
+    /** The data type of the field. */
+    type: FieldType;
+    
+    /** Whether the field is mandatory. Defaults to false. */
+    required?: boolean;
+
+    /** Whether the field is unique in the table. */
+    unique?: boolean;
+
+    /** Whether to create a database index for this field. */
+    index?: boolean;
+
+    /** Whether the field is read-only in UI. */
+    readonly?: boolean;
+
+    /** Whether the field is hidden from default UI/API response. */
+    hidden?: boolean;
+    
+    /** The default value if not provided during creation. */
+    defaultValue?: any;
+
+    /** Tooltip or help text for the user. */
+    help_text?: string;
+    
+    /** 
+     * Whether the field allows multiple values. 
+     * Supported by 'select', 'lookup', 'file', 'image'.
+     */
+    multiple?: boolean;
+    
+    /** 
+     * Options for select fields.
+     * List of available choices for select/multiselect fields.
+     */
+    options?: FieldOption[];
+    
+    /**
+     * Reference to another object for lookup/master_detail fields.
+     * Specifies the target object name for relationship fields.
+     */
+    reference_to?: string;
+    
+    // Validation properties
+    /** Minimum for number/currency/percent. */
+    min?: number;
+    /** Maximum for number/currency/percent. */
+    max?: number;
+    /** Minimum length for text based fields. */
+    min_length?: number;
+    /** Maximum length for text based fields. */
+    max_length?: number;
+    /** Regular expression pattern for validation. */
+    regex?: string;
+
+    // Vector properties
+    /** Dimension of the vector for 'vector' type fields. */
+    dimension?: number;
+}

package/src/hook.ts

@@ -0,0 +1,132 @@
+import { UnifiedQuery } from "./query";
+
+/**
+ * Standard CRUD operations supported by hooks.
+ */
+export type HookOperation = 'find' | 'count' | 'create' | 'update' | 'delete';
+
+/**
+ * Execution timing relative to the database operation.
+ */
+export type HookTiming = 'before' | 'after';
+
+/**
+ * Minimal API surface exposed to hooks for performing side-effects or checks.
+ */
+export interface HookAPI {
+    // We use 'any' here to avoid circular dependencies with core/ObjectQL
+    // In practice, this is the ObjectQL instance.
+    find(objectName: string, query?: any): Promise<any[]>;
+    findOne(objectName: string, id: string | number): Promise<any>;
+    count(objectName: string, query?: any): Promise<number>;
+    create(objectName: string, data: any): Promise<any>;
+    update(objectName: string, id: string | number, data: any): Promise<any>;
+    delete(objectName: string, id: string | number): Promise<any>;
+}
+
+/**
+ * Base context available in all hooks.
+ */
+export interface BaseHookContext<T = any> {
+    /** The name of the object (entity) being acted upon. */
+    objectName: string;
+    
+    /** The triggering operation. */
+    operation: HookOperation;
+    
+    /** Access to the database/engine to perform extra queries. */
+    api: HookAPI;
+    
+    /** User/Session context (Authentication info). */
+    user?: {
+        id: string | number;
+        [key: string]: any;
+    };
+
+    /** 
+     * Shared state for passing data between matching 'before' and 'after' hooks.
+     * e.g. Calculate a diff in 'beforeUpdate' and read it in 'afterUpdate'.
+     */
+    state: Record<string, any>;
+}
+
+/**
+ * Context for Retrieval operations (Find, Count).
+ */
+export interface RetrievalHookContext<T = any> extends BaseHookContext<T> {
+    operation: 'find' | 'count';
+    
+    /** The query criteria being executed. Modifiable in 'before' hooks. */
+    query: any;
+    
+    /** The result of the query. Only available in 'after' hooks. */
+    result?: T[] | number;
+}
+
+/**
+ * Context for Modification operations (Create, Update, Delete).
+ */
+export interface MutationHookContext<T = any> extends BaseHookContext<T> {
+    operation: 'create' | 'update' | 'delete';
+    
+    /** The record ID. Undefined for 'create'. */
+    id?: string | number;
+    
+    /** 
+     * The incoming data changes. 
+     * - For 'create': The full object to insert.
+     * - For 'update': The partial fields to update.
+     * - For 'delete': Undefined.
+     */
+    data?: Partial<T>;
+
+    /**
+     * The final result record from the database.
+     * Only available in 'after' hooks.
+     */
+    result?: T;
+}
+
+/**
+ * Specialized context for Updates, including change tracking.
+ */
+export interface UpdateHookContext<T = any> extends MutationHookContext<T> {
+    operation: 'update';
+    
+    /** 
+     * The record state BEFORE the update.
+     * Useful for comparison logic (e.g. status changed from A to B).
+     * Note: This may require a pre-fetch lookup depending on engine configuration.
+     */
+    previousData?: T;
+    
+    /**
+     * Helper to check if a specific field is being modified.
+     * Checks if the field exists in 'data' AND is different from 'previousData'.
+     */
+    isModified(field: keyof T): boolean;
+}
+
+/**
+ * Definition interface for a set of hooks for a specific object.
+ */
+export interface ObjectHookDefinition<T = any> {
+    beforeFind?: (ctx: RetrievalHookContext<T>) => Promise<void> | void;
+    afterFind?: (ctx: RetrievalHookContext<T>) => Promise<void> | void;
+    
+    beforeCount?: (ctx: RetrievalHookContext<T>) => Promise<void> | void;
+    afterCount?: (ctx: RetrievalHookContext<T>) => Promise<void> | void;
+    
+    beforeDelete?: (ctx: MutationHookContext<T>) => Promise<void> | void;
+    afterDelete?: (ctx: MutationHookContext<T>) => Promise<void> | void;
+    
+    beforeCreate?: (ctx: MutationHookContext<T>) => Promise<void> | void;
+    afterCreate?: (ctx: MutationHookContext<T>) => Promise<void> | void;
+    
+    beforeUpdate?: (ctx: UpdateHookContext<T>) => Promise<void> | void;
+    afterUpdate?: (ctx: UpdateHookContext<T>) => Promise<void> | void;
+}
+
+export type HookName = keyof ObjectHookDefinition;
+export type HookContext<T = any> = RetrievalHookContext<T> | MutationHookContext<T> | UpdateHookContext<T>;
+export type HookHandler<T = any> = (ctx: HookContext<T>) => Promise<void> | void;

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './field';
+export * from './object';
+export * from './types';
+export * from './driver';
+export * from './query';
+export * from './registry';
+export * from './hook';
+export * from './action';
+
+

package/src/object.ts

@@ -0,0 +1,49 @@
+import { FieldConfig } from './field';
+import { ActionConfig } from './action';
+
+export interface IndexConfig {
+    /** List of fields involved in the index */
+    fields: string[];
+    /** Whether the index enforces uniqueness */
+    unique?: boolean;
+}
+
+export interface AiSearchConfig {
+    /** Enable semantic search for this object */
+    enabled: boolean;
+    /** Fields to include in the embedding generation */
+    fields: string[];
+    /** The AI model to use for embedding (e.g. 'openai/text-embedding-3-small') */
+    model?: string;
+    /** Optional: Target vector field name if manually defined */
+    target_field?: string;
+}
+
+export interface ObjectAiConfig {
+    /** Configuration for semantic search / RAG */
+    search?: AiSearchConfig;
+}
+
+export interface ObjectConfig {
+    name: string;
+    datasource?: string; // The name of the datasource to use
+    label?: string;
+    icon?: string;
+    description?: string;
+    
+    fields: Record<string, FieldConfig>;
+    indexes?: Record<string, IndexConfig>;
+    /** AI capabilities configuration */
+    ai?: ObjectAiConfig;
+    actions?: Record<string, ActionConfig>;
+}
+
+/**
+ * Base interface for all ObjectQL documents.
+ */
+export interface ObjectDoc {
+    _id?: string | number;
+    created_at?: Date | string;
+    updated_at?: Date | string;
+    [key: string]: any;
+}

package/src/query.ts

@@ -0,0 +1,23 @@
+export type FilterCriterion = [string, string, any];
+export type FilterExpression = FilterCriterion | 'and' | 'or' | FilterExpression[];
+
+export type AggregateFunction = 'count' | 'sum' | 'avg' | 'min' | 'max';
+
+export interface AggregateOption {
+    func: AggregateFunction;
+    field: string;
+    alias?: string; // Optional: rename the result field
+}
+
+export interface UnifiedQuery {
+    fields?: string[];
+    filters?: FilterExpression[];
+    sort?: [string, 'asc' | 'desc'][];
+    skip?: number;
+    limit?: number;
+    expand?: Record<string, UnifiedQuery>;
+    
+    // === Aggregation Support ===
+    groupBy?: string[];
+    aggregate?: AggregateOption[];
+}

package/src/registry.ts

@@ -0,0 +1,54 @@
+export interface Metadata {
+    type: string;
+    id: string;
+    path?: string;
+    package?: string;
+    content: any;
+}
+
+export class ObjectRegistry {
+    // Map<type, Map<id, Metadata>>
+    private store: Map<string, Map<string, Metadata>> = new Map();
+
+    register(type: string, metadata: Metadata) {
+        if (!this.store.has(type)) {
+            this.store.set(type, new Map());
+        }
+        this.store.get(type)!.set(metadata.id, metadata);
+    }
+
+    unregister(type: string, id: string) {
+        this.store.get(type)?.delete(id);
+    }
+    
+    unregisterPackage(packageName: string) {
+        for (const [type, map] of this.store.entries()) {
+            const entriesToDelete: string[] = [];
+            
+            for (const [id, meta] of map.entries()) {
+                if (meta.package === packageName) {
+                    entriesToDelete.push(id);
+                }
+            }
+            
+            // Delete all collected entries
+            for (const id of entriesToDelete) {
+                map.delete(id);
+            }
+        }
+    }
+
+    get<T = any>(type: string, id: string): T | undefined {
+        return this.store.get(type)?.get(id)?.content as T;
+    }
+
+    list<T = any>(type: string): T[] {
+        const map = this.store.get(type);
+        if (!map) return [];
+        return Array.from(map.values()).map(m => m.content as T);
+    }
+    
+    getEntry(type: string, id: string): Metadata | undefined {
+        return this.store.get(type)?.get(id);
+    }
+}