@objectstack/objectql 2.0.4 → 2.0.5

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/objectql@2.0.4 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
-CJS dist/index.js     62.77 KB
-CJS dist/index.js.map 126.84 KB
-CJS ⚡️ Build success in 81ms
-ESM dist/index.mjs     61.35 KB
-ESM dist/index.mjs.map 126.13 KB
-ESM ⚡️ Build success in 94ms
+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 12002ms
-DTS dist/index.d.mts 66.66 KB
-DTS dist/index.d.ts  66.66 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,14 @@
 # @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

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';
 
@@ -1290,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)
  */
@@ -1311,6 +1335,7 @@ declare class ObjectQL implements IDataEngine {
     private defaultDriver;
     private logger;
     private hooks;
+    private middlewares;
     private hostContext;
     constructor(hostContext?: Record<string, any>);
     /**
@@ -1335,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)
      *
@@ -1653,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 {
@@ -1664,6 +1791,16 @@ 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
@@ -1671,4 +1808,4 @@ declare class ObjectQLPlugin implements Plugin {
     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';
 
@@ -1290,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)
  */
@@ -1311,6 +1335,7 @@ declare class ObjectQL implements IDataEngine {
     private defaultDriver;
     private logger;
     private hooks;
+    private middlewares;
     private hostContext;
     constructor(hostContext?: Record<string, any>);
     /**
@@ -1335,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)
      *
@@ -1653,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 {
@@ -1664,6 +1791,16 @@ 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
@@ -1671,4 +1808,4 @@ declare class ObjectQLPlugin implements Plugin {
     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 };