@objectstack/objectql 2.0.3 → 2.0.5

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/objectql@2.0.3 build /home/runner/work/spec/spec/packages/objectql
+> @objectstack/objectql@2.0.5 build /home/runner/work/spec/spec/packages/objectql
 > tsup --config ../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     58.00 KB
-ESM dist/index.mjs.map 118.58 KB
-ESM ⚡️ Build success in 102ms
-CJS dist/index.js     59.42 KB
-CJS dist/index.js.map 119.30 KB
-CJS ⚡️ Build success in 102ms
+ESM dist/index.mjs     71.78 KB
+ESM dist/index.mjs.map 145.78 KB
+ESM ⚡️ Build success in 150ms
+CJS dist/index.js     73.33 KB
+CJS dist/index.js.map 146.65 KB
+CJS ⚡️ Build success in 161ms
 DTS Build start
-DTS ⚡️ Build success in 9838ms
-DTS dist/index.d.mts 68.20 KB
-DTS dist/index.d.ts  68.20 KB
+DTS ⚡️ Build success in 13396ms
+DTS dist/index.d.mts 70.72 KB
+DTS dist/index.d.ts  70.72 KB

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @objectstack/objectql
 
+## 2.0.5
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectstack/spec@2.0.5
+  - @objectstack/core@2.0.5
+  - @objectstack/types@2.0.5
+
+## 2.0.4
+
+### Patch Changes
+
+- Patch release for maintenance and stability improvements
+- Updated dependencies
+  - @objectstack/spec@2.0.4
+  - @objectstack/core@2.0.4
+  - @objectstack/types@2.0.4
+
 ## 2.0.3
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import * as _objectstack_spec_data from '@objectstack/spec/data';
-import { ServiceObject, ObjectOwnership, HookContext, DataEngineQueryOptions, DataEngineInsertOptions, DataEngineUpdateOptions, DataEngineDeleteOptions, DataEngineCountOptions, DataEngineAggregateOptions } from '@objectstack/spec/data';
-import { ObjectStackManifest, InstalledPackage } from '@objectstack/spec/kernel';
+import { ServiceObject, ObjectOwnership, HookContext, QueryAST, DataEngineQueryOptions, DataEngineInsertOptions, DataEngineUpdateOptions, DataEngineDeleteOptions, DataEngineCountOptions, DataEngineAggregateOptions } from '@objectstack/spec/data';
+import { ObjectStackManifest, InstalledPackage, ExecutionContext } from '@objectstack/spec/kernel';
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext } from '@objectstack/core';
 
@@ -1121,7 +1121,8 @@ declare class SchemaRegistry {
 
 declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     private engine;
-    constructor(engine: IDataEngine);
+    private getServicesRegistry?;
+    constructor(engine: IDataEngine, getServicesRegistry?: () => Map<string, any>);
     getDiscovery(): Promise<{
         version: string;
         apiName: string;
@@ -1139,99 +1140,26 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         endpoints: {
             data: string;
             metadata: string;
-            analytics: string;
-        };
-        services: {
-            metadata: {
-                enabled: boolean;
-                status: "degraded";
-                route: string;
-                provider: string;
-                message: string;
-            };
-            data: {
-                enabled: boolean;
-                status: "available";
-                route: string;
-                provider: string;
-            };
-            analytics: {
-                enabled: boolean;
-                status: "available";
-                route: string;
-                provider: string;
-            };
-            auth: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            automation: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            cache: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            queue: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            job: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            ui: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            workflow: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            realtime: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            notification: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            ai: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            i18n: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            graphql: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            'file-storage': {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            search: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
+            ui?: string | undefined;
+            auth?: string | undefined;
+            automation?: string | undefined;
+            storage?: string | undefined;
+            analytics?: string | undefined;
+            graphql?: string | undefined;
+            packages?: string | undefined;
+            workflow?: string | undefined;
+            realtime?: string | undefined;
+            notifications?: string | undefined;
+            ai?: string | undefined;
+            i18n?: string | undefined;
         };
+        services: Record<string, {
+            enabled: boolean;
+            status: "degraded" | "available" | "unavailable" | "stub";
+            route?: string | undefined;
+            provider?: string | undefined;
+            message?: string | undefined;
+        }>;
     }>;
     getMetaTypes(): Promise<{
         types: string[];
@@ -1362,6 +1290,30 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
 }
 
 type HookHandler = (context: HookContext) => Promise<void> | void;
+/**
+ * Per-object hook entry with priority support
+ */
+interface HookEntry {
+    handler: HookHandler;
+    object?: string | string[];
+    priority: number;
+}
+/**
+ * Operation Context for Middleware Chain
+ */
+interface OperationContext {
+    object: string;
+    operation: 'find' | 'findOne' | 'insert' | 'update' | 'delete' | 'count' | 'aggregate';
+    ast?: QueryAST;
+    data?: any;
+    options?: any;
+    context?: ExecutionContext;
+    result?: any;
+}
+/**
+ * Engine Middleware (Onion model)
+ */
+type EngineMiddleware = (ctx: OperationContext, next: () => Promise<void>) => Promise<void>;
 /**
  * Host Context provided to plugins (Internal ObjectQL Plugin System)
  */
@@ -1383,6 +1335,7 @@ declare class ObjectQL implements IDataEngine {
     private defaultDriver;
     private logger;
     private hooks;
+    private middlewares;
     private hostContext;
     constructor(hostContext?: Record<string, any>);
     /**
@@ -1407,9 +1360,30 @@ declare class ObjectQL implements IDataEngine {
      * Register a hook
      * @param event The event name (e.g. 'beforeFind', 'afterInsert')
      * @param handler The handler function
+     * @param options Optional: target object(s) and priority
      */
-    registerHook(event: string, handler: HookHandler): void;
+    registerHook(event: string, handler: HookHandler, options?: {
+        object?: string | string[];
+        priority?: number;
+    }): void;
     triggerHooks(event: string, context: HookContext): Promise<void>;
+    /**
+     * Register a middleware function
+     * Middlewares execute in onion model around every data operation.
+     * @param fn The middleware function
+     * @param options Optional: target object filter
+     */
+    registerMiddleware(fn: EngineMiddleware, options?: {
+        object?: string;
+    }): void;
+    /**
+     * Execute an operation through the middleware chain
+     */
+    private executeWithMiddleware;
+    /**
+     * Build a HookContext.session from ExecutionContext
+     */
+    private buildSession;
     /**
      * Register contribution (Manifest)
      *
@@ -1725,6 +1699,87 @@ declare class ObjectQL implements IDataEngine {
     count(object: string, query?: DataEngineCountOptions): Promise<number>;
     aggregate(object: string, query: DataEngineAggregateOptions): Promise<any[]>;
     execute(command: any, options?: Record<string, any>): Promise<any>;
+    /**
+     * Create a scoped execution context bound to this engine.
+     *
+     * Usage:
+     *   const ctx = engine.createContext({ userId: '...', tenantId: '...' });
+     *   const users = ctx.object('user');
+     *   await users.find({ filter: { status: 'active' } });
+     */
+    createContext(ctx: Partial<ExecutionContext>): ScopedContext;
+}
+/**
+ * Repository scoped to a single object, bound to an execution context.
+ */
+declare class ObjectRepository {
+    private objectName;
+    private context;
+    private engine;
+    constructor(objectName: string, context: ExecutionContext, engine: IDataEngine);
+    find(query?: any): Promise<any[]>;
+    findOne(query?: any): Promise<any>;
+    insert(data: any): Promise<any>;
+    update(data: any, options?: any): Promise<any>;
+    delete(options?: any): Promise<any>;
+    count(query?: any): Promise<number>;
+}
+/**
+ * Scoped execution context with object() accessor.
+ */
+declare class ScopedContext {
+    private executionContext;
+    private engine;
+    constructor(executionContext: ExecutionContext, engine: IDataEngine);
+    /** Get a repository scoped to this context */
+    object(name: string): ObjectRepository;
+    /** Create an elevated (system) context */
+    sudo(): ScopedContext;
+    get userId(): string | undefined;
+    get tenantId(): string | undefined;
+    get roles(): string[];
+}
+
+/**
+ * MetadataFacade
+ *
+ * Provides a clean, injectable interface over SchemaRegistry.
+ * Registered as the 'metadata' kernel service to eliminate
+ * downstream packages needing to manually wrap SchemaRegistry.
+ */
+declare class MetadataFacade {
+    /**
+     * Register a metadata item
+     */
+    register(type: string, definition: any): void;
+    /**
+     * Get a metadata item by type and name
+     */
+    get(type: string, name: string): any;
+    /**
+     * Get the raw entry (with metadata wrapper)
+     */
+    getEntry(type: string, name: string): any;
+    /**
+     * List all items of a type
+     */
+    list(type: string): any[];
+    /**
+     * Unregister a metadata item
+     */
+    unregister(type: string, name: string): void;
+    /**
+     * Unregister all metadata from a package
+     */
+    unregisterPackage(packageName: string): void;
+    /**
+     * Convenience: get object definition
+     */
+    getObject(name: string): any;
+    /**
+     * Convenience: list all objects
+     */
+    listObjects(): any[];
 }
 
 declare class ObjectQLPlugin implements Plugin {
@@ -1736,6 +1791,21 @@ declare class ObjectQLPlugin implements Plugin {
     constructor(ql?: ObjectQL, hostContext?: Record<string, any>);
     init: (ctx: PluginContext) => Promise<void>;
     start: (ctx: PluginContext) => Promise<void>;
+    /**
+     * Register built-in audit hooks for auto-stamping createdBy/modifiedBy
+     * and fetching previousData for update/delete operations.
+     */
+    private registerAuditHooks;
+    /**
+     * Register tenant isolation middleware that auto-injects space_id filter
+     * for multi-tenant operations.
+     */
+    private registerTenantMiddleware;
+    /**
+     * Load metadata from external metadata service into ObjectQL registry
+     * This enables ObjectQL to use file-based or remote metadata
+     */
+    private loadMetadataFromService;
 }
 
-export { DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type HookHandler, type ObjectContributor, ObjectQL, type ObjectQLHostContext, ObjectQLPlugin, ObjectStackProtocolImplementation, RESERVED_NAMESPACES, SchemaRegistry, computeFQN, parseFQN };
+export { DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type HookEntry, type HookHandler, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, ScopedContext, computeFQN, parseFQN };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import * as _objectstack_spec_data from '@objectstack/spec/data';
-import { ServiceObject, ObjectOwnership, HookContext, DataEngineQueryOptions, DataEngineInsertOptions, DataEngineUpdateOptions, DataEngineDeleteOptions, DataEngineCountOptions, DataEngineAggregateOptions } from '@objectstack/spec/data';
-import { ObjectStackManifest, InstalledPackage } from '@objectstack/spec/kernel';
+import { ServiceObject, ObjectOwnership, HookContext, QueryAST, DataEngineQueryOptions, DataEngineInsertOptions, DataEngineUpdateOptions, DataEngineDeleteOptions, DataEngineCountOptions, DataEngineAggregateOptions } from '@objectstack/spec/data';
+import { ObjectStackManifest, InstalledPackage, ExecutionContext } from '@objectstack/spec/kernel';
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext } from '@objectstack/core';
 
@@ -1121,7 +1121,8 @@ declare class SchemaRegistry {
 
 declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     private engine;
-    constructor(engine: IDataEngine);
+    private getServicesRegistry?;
+    constructor(engine: IDataEngine, getServicesRegistry?: () => Map<string, any>);
     getDiscovery(): Promise<{
         version: string;
         apiName: string;
@@ -1139,99 +1140,26 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         endpoints: {
             data: string;
             metadata: string;
-            analytics: string;
-        };
-        services: {
-            metadata: {
-                enabled: boolean;
-                status: "degraded";
-                route: string;
-                provider: string;
-                message: string;
-            };
-            data: {
-                enabled: boolean;
-                status: "available";
-                route: string;
-                provider: string;
-            };
-            analytics: {
-                enabled: boolean;
-                status: "available";
-                route: string;
-                provider: string;
-            };
-            auth: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            automation: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            cache: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            queue: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            job: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            ui: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            workflow: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            realtime: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            notification: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            ai: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            i18n: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            graphql: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            'file-storage': {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
-            search: {
-                enabled: boolean;
-                status: "unavailable";
-                message: string;
-            };
+            ui?: string | undefined;
+            auth?: string | undefined;
+            automation?: string | undefined;
+            storage?: string | undefined;
+            analytics?: string | undefined;
+            graphql?: string | undefined;
+            packages?: string | undefined;
+            workflow?: string | undefined;
+            realtime?: string | undefined;
+            notifications?: string | undefined;
+            ai?: string | undefined;
+            i18n?: string | undefined;
         };
+        services: Record<string, {
+            enabled: boolean;
+            status: "degraded" | "available" | "unavailable" | "stub";
+            route?: string | undefined;
+            provider?: string | undefined;
+            message?: string | undefined;
+        }>;
     }>;
     getMetaTypes(): Promise<{
         types: string[];
@@ -1362,6 +1290,30 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
 }
 
 type HookHandler = (context: HookContext) => Promise<void> | void;
+/**
+ * Per-object hook entry with priority support
+ */
+interface HookEntry {
+    handler: HookHandler;
+    object?: string | string[];
+    priority: number;
+}
+/**
+ * Operation Context for Middleware Chain
+ */
+interface OperationContext {
+    object: string;
+    operation: 'find' | 'findOne' | 'insert' | 'update' | 'delete' | 'count' | 'aggregate';
+    ast?: QueryAST;
+    data?: any;
+    options?: any;
+    context?: ExecutionContext;
+    result?: any;
+}
+/**
+ * Engine Middleware (Onion model)
+ */
+type EngineMiddleware = (ctx: OperationContext, next: () => Promise<void>) => Promise<void>;
 /**
  * Host Context provided to plugins (Internal ObjectQL Plugin System)
  */
@@ -1383,6 +1335,7 @@ declare class ObjectQL implements IDataEngine {
     private defaultDriver;
     private logger;
     private hooks;
+    private middlewares;
     private hostContext;
     constructor(hostContext?: Record<string, any>);
     /**
@@ -1407,9 +1360,30 @@ declare class ObjectQL implements IDataEngine {
      * Register a hook
      * @param event The event name (e.g. 'beforeFind', 'afterInsert')
      * @param handler The handler function
+     * @param options Optional: target object(s) and priority
      */
-    registerHook(event: string, handler: HookHandler): void;
+    registerHook(event: string, handler: HookHandler, options?: {
+        object?: string | string[];
+        priority?: number;
+    }): void;
     triggerHooks(event: string, context: HookContext): Promise<void>;
+    /**
+     * Register a middleware function
+     * Middlewares execute in onion model around every data operation.
+     * @param fn The middleware function
+     * @param options Optional: target object filter
+     */
+    registerMiddleware(fn: EngineMiddleware, options?: {
+        object?: string;
+    }): void;
+    /**
+     * Execute an operation through the middleware chain
+     */
+    private executeWithMiddleware;
+    /**
+     * Build a HookContext.session from ExecutionContext
+     */
+    private buildSession;
     /**
      * Register contribution (Manifest)
      *
@@ -1725,6 +1699,87 @@ declare class ObjectQL implements IDataEngine {
     count(object: string, query?: DataEngineCountOptions): Promise<number>;
     aggregate(object: string, query: DataEngineAggregateOptions): Promise<any[]>;
     execute(command: any, options?: Record<string, any>): Promise<any>;
+    /**
+     * Create a scoped execution context bound to this engine.
+     *
+     * Usage:
+     *   const ctx = engine.createContext({ userId: '...', tenantId: '...' });
+     *   const users = ctx.object('user');
+     *   await users.find({ filter: { status: 'active' } });
+     */
+    createContext(ctx: Partial<ExecutionContext>): ScopedContext;
+}
+/**
+ * Repository scoped to a single object, bound to an execution context.
+ */
+declare class ObjectRepository {
+    private objectName;
+    private context;
+    private engine;
+    constructor(objectName: string, context: ExecutionContext, engine: IDataEngine);
+    find(query?: any): Promise<any[]>;
+    findOne(query?: any): Promise<any>;
+    insert(data: any): Promise<any>;
+    update(data: any, options?: any): Promise<any>;
+    delete(options?: any): Promise<any>;
+    count(query?: any): Promise<number>;
+}
+/**
+ * Scoped execution context with object() accessor.
+ */
+declare class ScopedContext {
+    private executionContext;
+    private engine;
+    constructor(executionContext: ExecutionContext, engine: IDataEngine);
+    /** Get a repository scoped to this context */
+    object(name: string): ObjectRepository;
+    /** Create an elevated (system) context */
+    sudo(): ScopedContext;
+    get userId(): string | undefined;
+    get tenantId(): string | undefined;
+    get roles(): string[];
+}
+
+/**
+ * MetadataFacade
+ *
+ * Provides a clean, injectable interface over SchemaRegistry.
+ * Registered as the 'metadata' kernel service to eliminate
+ * downstream packages needing to manually wrap SchemaRegistry.
+ */
+declare class MetadataFacade {
+    /**
+     * Register a metadata item
+     */
+    register(type: string, definition: any): void;
+    /**
+     * Get a metadata item by type and name
+     */
+    get(type: string, name: string): any;
+    /**
+     * Get the raw entry (with metadata wrapper)
+     */
+    getEntry(type: string, name: string): any;
+    /**
+     * List all items of a type
+     */
+    list(type: string): any[];
+    /**
+     * Unregister a metadata item
+     */
+    unregister(type: string, name: string): void;
+    /**
+     * Unregister all metadata from a package
+     */
+    unregisterPackage(packageName: string): void;
+    /**
+     * Convenience: get object definition
+     */
+    getObject(name: string): any;
+    /**
+     * Convenience: list all objects
+     */
+    listObjects(): any[];
 }
 
 declare class ObjectQLPlugin implements Plugin {
@@ -1736,6 +1791,21 @@ declare class ObjectQLPlugin implements Plugin {
     constructor(ql?: ObjectQL, hostContext?: Record<string, any>);
     init: (ctx: PluginContext) => Promise<void>;
     start: (ctx: PluginContext) => Promise<void>;
+    /**
+     * Register built-in audit hooks for auto-stamping createdBy/modifiedBy
+     * and fetching previousData for update/delete operations.
+     */
+    private registerAuditHooks;
+    /**
+     * Register tenant isolation middleware that auto-injects space_id filter
+     * for multi-tenant operations.
+     */
+    private registerTenantMiddleware;
+    /**
+     * Load metadata from external metadata service into ObjectQL registry
+     * This enables ObjectQL to use file-based or remote metadata
+     */
+    private loadMetadataFromService;
 }
 
-export { DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type HookHandler, type ObjectContributor, ObjectQL, type ObjectQLHostContext, ObjectQLPlugin, ObjectStackProtocolImplementation, RESERVED_NAMESPACES, SchemaRegistry, computeFQN, parseFQN };
+export { DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type HookEntry, type HookHandler, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, ScopedContext, computeFQN, parseFQN };