@objectstack/objectql 2.0.7 → 3.0.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/objectql@2.0.7 build /home/runner/work/spec/spec/packages/objectql
+> @objectstack/objectql@3.0.0 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     73.19 KB
-CJS dist/index.js.map 146.61 KB
-CJS ⚡️ Build success in 118ms
-ESM dist/index.mjs     71.64 KB
-ESM dist/index.mjs.map 145.73 KB
-ESM ⚡️ Build success in 146ms
+ESM dist/index.mjs     75.55 KB
+ESM dist/index.mjs.map 152.89 KB
+ESM ⚡️ Build success in 120ms
+CJS dist/index.js     77.09 KB
+CJS dist/index.js.map 153.77 KB
+CJS ⚡️ Build success in 127ms
 DTS Build start
-DTS ⚡️ Build success in 13509ms
-DTS dist/index.d.mts 71.96 KB
-DTS dist/index.d.ts  71.96 KB
+DTS ⚡️ Build success in 13686ms
+DTS dist/index.d.mts 75.15 KB
+DTS dist/index.d.ts  75.15 KB

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @objectstack/objectql
 
+## 3.0.0
+
+### Major Changes
+
+- Release v3.0.0 — unified version bump for all ObjectStack packages.
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectstack/spec@3.0.0
+  - @objectstack/core@3.0.0
+  - @objectstack/types@3.0.0
+
 ## 2.0.7
 
 ### Patch Changes

package/dist/index.d.mts

@@ -353,6 +353,8 @@ declare class SchemaRegistry {
                     threshold: number;
                 } | undefined;
             } | undefined;
+            group?: string | undefined;
+            conditionalRequired?: string | undefined;
             inlineHelpText?: string | undefined;
             trackFeedHistory?: boolean | undefined;
             caseSensitive?: boolean | undefined;
@@ -430,6 +432,12 @@ declare class SchemaRegistry {
                 description?: string | undefined;
             }[]> | undefined;
         }> | undefined;
+        displayNameField?: string | undefined;
+        recordName?: {
+            type: "text" | "autonumber";
+            displayFormat?: string | undefined;
+            startNumber?: number | undefined;
+        } | undefined;
         titleFormat?: string | undefined;
         compactLayout?: string[] | undefined;
         search?: {
@@ -457,7 +465,7 @@ declare class SchemaRegistry {
         label: string | {
             key: string;
             defaultValue?: string | undefined;
-            params?: Record<string, any> | undefined;
+            params?: Record<string, string | number | boolean> | undefined;
         };
         active: boolean;
         isDefault: boolean;
@@ -465,7 +473,7 @@ declare class SchemaRegistry {
         description?: string | {
             key: string;
             defaultValue?: string | undefined;
-            params?: Record<string, any> | undefined;
+            params?: Record<string, string | number | boolean> | undefined;
         } | undefined;
         icon?: string | undefined;
         branding?: {
@@ -486,7 +494,7 @@ declare class SchemaRegistry {
             ariaLabel?: string | {
                 key: string;
                 defaultValue?: string | undefined;
-                params?: Record<string, any> | undefined;
+                params?: Record<string, string | number | boolean> | undefined;
             } | undefined;
             ariaDescribedBy?: string | undefined;
             role?: string | undefined;
@@ -797,10 +805,12 @@ declare class SchemaRegistry {
                 } | undefined;
             } | undefined;
         };
-        status: "error" | "disabled" | "installed" | "installing" | "uninstalling";
+        status: "error" | "disabled" | "installed" | "installing" | "upgrading" | "uninstalling";
         enabled: boolean;
         installedAt?: string | undefined;
         updatedAt?: string | undefined;
+        installedVersion?: string | undefined;
+        previousVersion?: string | undefined;
         statusChangedAt?: string | undefined;
         errorMessage?: string | undefined;
         settings?: Record<string, unknown> | undefined;
@@ -1356,6 +1366,7 @@ declare class ObjectQL implements IDataEngine {
     private logger;
     private hooks;
     private middlewares;
+    private actions;
     private hostContext;
     constructor(hostContext?: Record<string, any>);
     /**
@@ -1387,6 +1398,24 @@ declare class ObjectQL implements IDataEngine {
         priority?: number;
     }): void;
     triggerHooks(event: string, context: HookContext): Promise<void>;
+    /**
+     * Register a named action on an object.
+     * Actions are custom business logic callable via `repo.execute(actionName, params)`.
+     *
+     * @param objectName Target object
+     * @param actionName Unique action name within the object
+     * @param handler Handler function
+     * @param packageName Optional package owner (for cleanup)
+     */
+    registerAction(objectName: string, actionName: string, handler: (ctx: any) => Promise<any> | any, packageName?: string): void;
+    /**
+     * Execute a named action on an object.
+     */
+    executeAction(objectName: string, actionName: string, ctx: any): Promise<any>;
+    /**
+     * Remove all actions registered by a specific package.
+     */
+    removeActionsByPackage(packageName: string): void;
     /**
      * Register a middleware function
      * Middlewares execute in onion model around every data operation.
@@ -1590,6 +1619,8 @@ declare class ObjectQL implements IDataEngine {
                     threshold: number;
                 } | undefined;
             } | undefined;
+            group?: string | undefined;
+            conditionalRequired?: string | undefined;
             inlineHelpText?: string | undefined;
             trackFeedHistory?: boolean | undefined;
             caseSensitive?: boolean | undefined;
@@ -1667,6 +1698,12 @@ declare class ObjectQL implements IDataEngine {
                 description?: string | undefined;
             }[]> | undefined;
         }> | undefined;
+        displayNameField?: string | undefined;
+        recordName?: {
+            type: "text" | "autonumber";
+            displayFormat?: string | undefined;
+            startNumber?: number | undefined;
+        } | undefined;
         titleFormat?: string | undefined;
         compactLayout?: string[] | undefined;
         search?: {
@@ -1731,21 +1768,41 @@ declare class ObjectQL implements IDataEngine {
 }
 /**
  * Repository scoped to a single object, bound to an execution context.
+ *
+ * Provides both IDataEngine-style methods (find, insert, update, delete)
+ * and convenience aliases (create, updateById, deleteById) matching
+ * the @objectql/core ObjectRepository API.
  */
 declare class ObjectRepository {
     private objectName;
     private context;
     private engine;
-    constructor(objectName: string, context: ExecutionContext, engine: IDataEngine);
+    constructor(objectName: string, context: ExecutionContext, engine: IDataEngine & {
+        executeAction?: (o: string, a: string, c: any) => Promise<any>;
+    });
     find(query?: any): Promise<any[]>;
     findOne(query?: any): Promise<any>;
     insert(data: any): Promise<any>;
+    /** Alias for insert() — matches @objectql/core convention */
+    create(data: any): Promise<any>;
     update(data: any, options?: any): Promise<any>;
+    /** Update a single record by ID */
+    updateById(id: string | number, data: any): Promise<any>;
     delete(options?: any): Promise<any>;
+    /** Delete a single record by ID */
+    deleteById(id: string | number): Promise<any>;
     count(query?: any): Promise<number>;
+    /** Aggregate query */
+    aggregate(query?: any): Promise<any[]>;
+    /** Execute a named action registered on this object */
+    execute(actionName: string, params?: any): Promise<any>;
 }
 /**
  * Scoped execution context with object() accessor.
+ *
+ * Provides identity (userId, tenantId/spaceId, roles),
+ * repository access via object(), privilege escalation via sudo(),
+ * and transactional execution via transaction().
  */
 declare class ScopedContext {
     private executionContext;
@@ -1755,9 +1812,25 @@ declare class ScopedContext {
     object(name: string): ObjectRepository;
     /** Create an elevated (system) context */
     sudo(): ScopedContext;
+    /**
+     * Execute a callback within a database transaction.
+     *
+     * The callback receives a new ScopedContext whose operations
+     * share the same transaction handle. If the callback throws,
+     * the transaction is rolled back; otherwise it is committed.
+     *
+     * Falls back to non-transactional execution if the driver
+     * does not support transactions.
+     */
+    transaction(callback: (trxCtx: ScopedContext) => Promise<any>): Promise<any>;
     get userId(): string | undefined;
     get tenantId(): string | undefined;
+    /** Alias for tenantId — matches ObjectQLContext.spaceId convention */
+    get spaceId(): string | undefined;
     get roles(): string[];
+    get isSystem(): boolean;
+    /** Internal: expose the transaction handle for driver-level access */
+    get transactionHandle(): unknown;
 }
 
 /**

package/dist/index.d.ts

@@ -353,6 +353,8 @@ declare class SchemaRegistry {
                     threshold: number;
                 } | undefined;
             } | undefined;
+            group?: string | undefined;
+            conditionalRequired?: string | undefined;
             inlineHelpText?: string | undefined;
             trackFeedHistory?: boolean | undefined;
             caseSensitive?: boolean | undefined;
@@ -430,6 +432,12 @@ declare class SchemaRegistry {
                 description?: string | undefined;
             }[]> | undefined;
         }> | undefined;
+        displayNameField?: string | undefined;
+        recordName?: {
+            type: "text" | "autonumber";
+            displayFormat?: string | undefined;
+            startNumber?: number | undefined;
+        } | undefined;
         titleFormat?: string | undefined;
         compactLayout?: string[] | undefined;
         search?: {
@@ -457,7 +465,7 @@ declare class SchemaRegistry {
         label: string | {
             key: string;
             defaultValue?: string | undefined;
-            params?: Record<string, any> | undefined;
+            params?: Record<string, string | number | boolean> | undefined;
         };
         active: boolean;
         isDefault: boolean;
@@ -465,7 +473,7 @@ declare class SchemaRegistry {
         description?: string | {
             key: string;
             defaultValue?: string | undefined;
-            params?: Record<string, any> | undefined;
+            params?: Record<string, string | number | boolean> | undefined;
         } | undefined;
         icon?: string | undefined;
         branding?: {
@@ -486,7 +494,7 @@ declare class SchemaRegistry {
             ariaLabel?: string | {
                 key: string;
                 defaultValue?: string | undefined;
-                params?: Record<string, any> | undefined;
+                params?: Record<string, string | number | boolean> | undefined;
             } | undefined;
             ariaDescribedBy?: string | undefined;
             role?: string | undefined;
@@ -797,10 +805,12 @@ declare class SchemaRegistry {
                 } | undefined;
             } | undefined;
         };
-        status: "error" | "disabled" | "installed" | "installing" | "uninstalling";
+        status: "error" | "disabled" | "installed" | "installing" | "upgrading" | "uninstalling";
         enabled: boolean;
         installedAt?: string | undefined;
         updatedAt?: string | undefined;
+        installedVersion?: string | undefined;
+        previousVersion?: string | undefined;
         statusChangedAt?: string | undefined;
         errorMessage?: string | undefined;
         settings?: Record<string, unknown> | undefined;
@@ -1356,6 +1366,7 @@ declare class ObjectQL implements IDataEngine {
     private logger;
     private hooks;
     private middlewares;
+    private actions;
     private hostContext;
     constructor(hostContext?: Record<string, any>);
     /**
@@ -1387,6 +1398,24 @@ declare class ObjectQL implements IDataEngine {
         priority?: number;
     }): void;
     triggerHooks(event: string, context: HookContext): Promise<void>;
+    /**
+     * Register a named action on an object.
+     * Actions are custom business logic callable via `repo.execute(actionName, params)`.
+     *
+     * @param objectName Target object
+     * @param actionName Unique action name within the object
+     * @param handler Handler function
+     * @param packageName Optional package owner (for cleanup)
+     */
+    registerAction(objectName: string, actionName: string, handler: (ctx: any) => Promise<any> | any, packageName?: string): void;
+    /**
+     * Execute a named action on an object.
+     */
+    executeAction(objectName: string, actionName: string, ctx: any): Promise<any>;
+    /**
+     * Remove all actions registered by a specific package.
+     */
+    removeActionsByPackage(packageName: string): void;
     /**
      * Register a middleware function
      * Middlewares execute in onion model around every data operation.
@@ -1590,6 +1619,8 @@ declare class ObjectQL implements IDataEngine {
                     threshold: number;
                 } | undefined;
             } | undefined;
+            group?: string | undefined;
+            conditionalRequired?: string | undefined;
             inlineHelpText?: string | undefined;
             trackFeedHistory?: boolean | undefined;
             caseSensitive?: boolean | undefined;
@@ -1667,6 +1698,12 @@ declare class ObjectQL implements IDataEngine {
                 description?: string | undefined;
             }[]> | undefined;
         }> | undefined;
+        displayNameField?: string | undefined;
+        recordName?: {
+            type: "text" | "autonumber";
+            displayFormat?: string | undefined;
+            startNumber?: number | undefined;
+        } | undefined;
         titleFormat?: string | undefined;
         compactLayout?: string[] | undefined;
         search?: {
@@ -1731,21 +1768,41 @@ declare class ObjectQL implements IDataEngine {
 }
 /**
  * Repository scoped to a single object, bound to an execution context.
+ *
+ * Provides both IDataEngine-style methods (find, insert, update, delete)
+ * and convenience aliases (create, updateById, deleteById) matching
+ * the @objectql/core ObjectRepository API.
  */
 declare class ObjectRepository {
     private objectName;
     private context;
     private engine;
-    constructor(objectName: string, context: ExecutionContext, engine: IDataEngine);
+    constructor(objectName: string, context: ExecutionContext, engine: IDataEngine & {
+        executeAction?: (o: string, a: string, c: any) => Promise<any>;
+    });
     find(query?: any): Promise<any[]>;
     findOne(query?: any): Promise<any>;
     insert(data: any): Promise<any>;
+    /** Alias for insert() — matches @objectql/core convention */
+    create(data: any): Promise<any>;
     update(data: any, options?: any): Promise<any>;
+    /** Update a single record by ID */
+    updateById(id: string | number, data: any): Promise<any>;
     delete(options?: any): Promise<any>;
+    /** Delete a single record by ID */
+    deleteById(id: string | number): Promise<any>;
     count(query?: any): Promise<number>;
+    /** Aggregate query */
+    aggregate(query?: any): Promise<any[]>;
+    /** Execute a named action registered on this object */
+    execute(actionName: string, params?: any): Promise<any>;
 }
 /**
  * Scoped execution context with object() accessor.
+ *
+ * Provides identity (userId, tenantId/spaceId, roles),
+ * repository access via object(), privilege escalation via sudo(),
+ * and transactional execution via transaction().
  */
 declare class ScopedContext {
     private executionContext;
@@ -1755,9 +1812,25 @@ declare class ScopedContext {
     object(name: string): ObjectRepository;
     /** Create an elevated (system) context */
     sudo(): ScopedContext;
+    /**
+     * Execute a callback within a database transaction.
+     *
+     * The callback receives a new ScopedContext whose operations
+     * share the same transaction handle. If the callback throws,
+     * the transaction is rolled back; otherwise it is committed.
+     *
+     * Falls back to non-transactional execution if the driver
+     * does not support transactions.
+     */
+    transaction(callback: (trxCtx: ScopedContext) => Promise<any>): Promise<any>;
     get userId(): string | undefined;
     get tenantId(): string | undefined;
+    /** Alias for tenantId — matches ObjectQLContext.spaceId convention */
+    get spaceId(): string | undefined;
     get roles(): string[];
+    get isSystem(): boolean;
+    /** Internal: expose the transaction handle for driver-level access */
+    get transactionHandle(): unknown;
 }
 
 /**

package/dist/index.js

@@ -1120,6 +1120,8 @@ var ObjectQL = class {
     ]);
     // Middleware chain (onion model)
     this.middlewares = [];
+    // Action registry: key = "objectName:actionName"
+    this.actions = /* @__PURE__ */ new Map();
     // Host provided context additions (e.g. Server router)
     this.hostContext = {};
     this.hostContext = hostContext;
@@ -1209,6 +1211,43 @@ var ObjectQL = class {
       await entry.handler(context);
     }
   }
+  // ========================================
+  // Action System
+  // ========================================
+  /**
+   * Register a named action on an object.
+   * Actions are custom business logic callable via `repo.execute(actionName, params)`.
+   *
+   * @param objectName Target object
+   * @param actionName Unique action name within the object
+   * @param handler Handler function
+   * @param packageName Optional package owner (for cleanup)
+   */
+  registerAction(objectName, actionName, handler, packageName) {
+    const key = `${objectName}:${actionName}`;
+    this.actions.set(key, { handler, package: packageName });
+    this.logger.debug("Registered action", { objectName, actionName, package: packageName });
+  }
+  /**
+   * Execute a named action on an object.
+   */
+  async executeAction(objectName, actionName, ctx) {
+    const entry = this.actions.get(`${objectName}:${actionName}`);
+    if (!entry) {
+      throw new Error(`Action '${actionName}' on object '${objectName}' not found`);
+    }
+    return entry.handler(ctx);
+  }
+  /**
+   * Remove all actions registered by a specific package.
+   */
+  removeActionsByPackage(packageName) {
+    for (const [key, entry] of this.actions.entries()) {
+      if (entry.package === packageName) {
+        this.actions.delete(key);
+      }
+    }
+  }
   /**
    * Register a middleware function
    * Middlewares execute in onion model around every data operation.
@@ -1876,24 +1915,61 @@ var ObjectRepository = class {
       context: this.context
     });
   }
+  /** Alias for insert() — matches @objectql/core convention */
+  async create(data) {
+    return this.insert(data);
+  }
   async update(data, options = {}) {
     return this.engine.update(this.objectName, data, {
       ...options,
       context: this.context
     });
   }
+  /** Update a single record by ID */
+  async updateById(id, data) {
+    return this.engine.update(this.objectName, { ...data, _id: id }, {
+      filter: { _id: id },
+      context: this.context
+    });
+  }
   async delete(options = {}) {
     return this.engine.delete(this.objectName, {
       ...options,
       context: this.context
     });
   }
+  /** Delete a single record by ID */
+  async deleteById(id) {
+    return this.engine.delete(this.objectName, {
+      filter: { _id: id },
+      context: this.context
+    });
+  }
   async count(query = {}) {
     return this.engine.count(this.objectName, {
       ...query,
       context: this.context
     });
   }
+  /** Aggregate query */
+  async aggregate(query = {}) {
+    return this.engine.aggregate(this.objectName, {
+      ...query,
+      context: this.context
+    });
+  }
+  /** Execute a named action registered on this object */
+  async execute(actionName, params) {
+    if (this.engine.executeAction) {
+      return this.engine.executeAction(this.objectName, actionName, {
+        ...params,
+        userId: this.context.userId,
+        tenantId: this.context.tenantId,
+        roles: this.context.roles
+      });
+    }
+    throw new Error(`Actions not supported by engine`);
+  }
 };
 var ScopedContext = class _ScopedContext {
   constructor(executionContext, engine) {
@@ -1911,15 +1987,58 @@ var ScopedContext = class _ScopedContext {
       this.engine
     );
   }
+  /**
+   * Execute a callback within a database transaction.
+   *
+   * The callback receives a new ScopedContext whose operations
+   * share the same transaction handle. If the callback throws,
+   * the transaction is rolled back; otherwise it is committed.
+   *
+   * Falls back to non-transactional execution if the driver
+   * does not support transactions.
+   */
+  async transaction(callback) {
+    const engine = this.engine;
+    const driver = engine.defaultDriver ? engine.drivers?.get(engine.defaultDriver) : void 0;
+    if (!driver?.beginTransaction) {
+      return callback(this);
+    }
+    const trx = await driver.beginTransaction();
+    const trxCtx = new _ScopedContext(
+      { ...this.executionContext, transaction: trx },
+      this.engine
+    );
+    try {
+      const result = await callback(trxCtx);
+      if (driver.commit) await driver.commit(trx);
+      else if (driver.commitTransaction) await driver.commitTransaction(trx);
+      return result;
+    } catch (error) {
+      if (driver.rollback) await driver.rollback(trx);
+      else if (driver.rollbackTransaction) await driver.rollbackTransaction(trx);
+      throw error;
+    }
+  }
   get userId() {
     return this.executionContext.userId;
   }
   get tenantId() {
     return this.executionContext.tenantId;
   }
+  /** Alias for tenantId — matches ObjectQLContext.spaceId convention */
+  get spaceId() {
+    return this.executionContext.tenantId;
+  }
   get roles() {
     return this.executionContext.roles;
   }
+  get isSystem() {
+    return this.executionContext.isSystem;
+  }
+  /** Internal: expose the transaction handle for driver-level access */
+  get transactionHandle() {
+    return this.executionContext.transaction;
+  }
 };
 
 // src/metadata-facade.ts