@objectstack/objectql 9.6.0 → 9.8.0

package/dist/index.d.mts

@@ -1065,6 +1065,30 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         id: any;
         record: any;
     }>;
+    /**
+     * Clone a record — read the source, drop engine-owned columns, and
+     * insert a fresh copy. Gated by the object's `enable.clone` capability
+     * (default `true`; only an explicit `enable.clone === false` disables it).
+     *
+     * Shallow by design: it duplicates the record's own scalar/business field
+     * values, not its related child records. The insert path re-stamps audit
+     * columns, regenerates `autonumber` fields, and recomputes derived
+     * (`formula`/`summary`) fields, so the copy is a valid new row rather than
+     * a byte-identical twin. Caller-supplied `overrides` are applied last and
+     * win over the copied values — the natural place to set a new `name`,
+     * clear a unique field, or reset status before insert.
+     */
+    cloneData(request: {
+        object: string;
+        id: string;
+        overrides?: Record<string, any>;
+        context?: any;
+    }): Promise<{
+        object: string;
+        id: any;
+        sourceId: string;
+        record: any;
+    }>;
     updateData(request: {
         object: string;
         id: string;
@@ -1999,6 +2023,23 @@ interface OperationContext {
     context?: ExecutionContext;
     result?: any;
 }
+/**
+ * Trailing options for the READ methods (find / findOne / count / aggregate).
+ *
+ * Historically the read methods took their execution context INSIDE the query
+ * (`query.context`), while the WRITE methods (insert / update) took it in a
+ * trailing `options.context`. That split was a footgun: the same `{ context }`
+ * object is correct as the 3rd arg to `insert` but was SILENTLY DROPPED as the
+ * 3rd arg to `find` — a class of bugs where an intended `isSystem` bypass just
+ * vanished (e.g. control-plane reads coming back empty once org-scoping hooks
+ * were added). We now ALSO accept `context` via this trailing options arg on the
+ * read methods, so "execution context goes in the trailing options argument" is
+ * one rule across reads and writes. `query.context` remains supported; when both
+ * are given, `options.context` wins (it is the explicit channel).
+ */
+interface EngineReadOptions {
+    context?: ExecutionContext;
+}
 /**
  * Engine Middleware (Onion model)
  */
@@ -2418,8 +2459,8 @@ declare class ObjectQL implements IDataEngine {
      * @returns Records with expanded lookup fields (IDs replaced by full objects)
      */
     private expandRelatedRecords;
-    find(object: string, query?: EngineQueryOptions): Promise<any[]>;
-    findOne(objectName: string, query?: EngineQueryOptions): Promise<any>;
+    find(object: string, query?: EngineQueryOptions, options?: EngineReadOptions): Promise<any[]>;
+    findOne(objectName: string, query?: EngineQueryOptions, options?: EngineReadOptions): Promise<any>;
     insert(object: string, data: any | any[], options?: DataEngineInsertOptions): Promise<any>;
     update(object: string, data: any, options?: EngineUpdateOptions): Promise<any>;
     /**
@@ -2436,8 +2477,8 @@ declare class ObjectQL implements IDataEngine {
      */
     private cascadeDeleteRelations;
     delete(object: string, options?: EngineDeleteOptions): Promise<any>;
-    count(object: string, query?: EngineCountOptions): Promise<number>;
-    aggregate(object: string, query: EngineAggregateOptions): Promise<any[]>;
+    count(object: string, query?: EngineCountOptions, options?: EngineReadOptions): Promise<number>;
+    aggregate(object: string, query: EngineAggregateOptions, options?: EngineReadOptions): Promise<any[]>;
     /**
      * Run raw driver-specific commands (SQL for SqlDriver, REST for RestDriver, …).
      *

package/dist/index.d.ts

@@ -1065,6 +1065,30 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         id: any;
         record: any;
     }>;
+    /**
+     * Clone a record — read the source, drop engine-owned columns, and
+     * insert a fresh copy. Gated by the object's `enable.clone` capability
+     * (default `true`; only an explicit `enable.clone === false` disables it).
+     *
+     * Shallow by design: it duplicates the record's own scalar/business field
+     * values, not its related child records. The insert path re-stamps audit
+     * columns, regenerates `autonumber` fields, and recomputes derived
+     * (`formula`/`summary`) fields, so the copy is a valid new row rather than
+     * a byte-identical twin. Caller-supplied `overrides` are applied last and
+     * win over the copied values — the natural place to set a new `name`,
+     * clear a unique field, or reset status before insert.
+     */
+    cloneData(request: {
+        object: string;
+        id: string;
+        overrides?: Record<string, any>;
+        context?: any;
+    }): Promise<{
+        object: string;
+        id: any;
+        sourceId: string;
+        record: any;
+    }>;
     updateData(request: {
         object: string;
         id: string;
@@ -1999,6 +2023,23 @@ interface OperationContext {
     context?: ExecutionContext;
     result?: any;
 }
+/**
+ * Trailing options for the READ methods (find / findOne / count / aggregate).
+ *
+ * Historically the read methods took their execution context INSIDE the query
+ * (`query.context`), while the WRITE methods (insert / update) took it in a
+ * trailing `options.context`. That split was a footgun: the same `{ context }`
+ * object is correct as the 3rd arg to `insert` but was SILENTLY DROPPED as the
+ * 3rd arg to `find` — a class of bugs where an intended `isSystem` bypass just
+ * vanished (e.g. control-plane reads coming back empty once org-scoping hooks
+ * were added). We now ALSO accept `context` via this trailing options arg on the
+ * read methods, so "execution context goes in the trailing options argument" is
+ * one rule across reads and writes. `query.context` remains supported; when both
+ * are given, `options.context` wins (it is the explicit channel).
+ */
+interface EngineReadOptions {
+    context?: ExecutionContext;
+}
 /**
  * Engine Middleware (Onion model)
  */
@@ -2418,8 +2459,8 @@ declare class ObjectQL implements IDataEngine {
      * @returns Records with expanded lookup fields (IDs replaced by full objects)
      */
     private expandRelatedRecords;
-    find(object: string, query?: EngineQueryOptions): Promise<any[]>;
-    findOne(objectName: string, query?: EngineQueryOptions): Promise<any>;
+    find(object: string, query?: EngineQueryOptions, options?: EngineReadOptions): Promise<any[]>;
+    findOne(objectName: string, query?: EngineQueryOptions, options?: EngineReadOptions): Promise<any>;
     insert(object: string, data: any | any[], options?: DataEngineInsertOptions): Promise<any>;
     update(object: string, data: any, options?: EngineUpdateOptions): Promise<any>;
     /**
@@ -2436,8 +2477,8 @@ declare class ObjectQL implements IDataEngine {
      */
     private cascadeDeleteRelations;
     delete(object: string, options?: EngineDeleteOptions): Promise<any>;
-    count(object: string, query?: EngineCountOptions): Promise<number>;
-    aggregate(object: string, query: EngineAggregateOptions): Promise<any[]>;
+    count(object: string, query?: EngineCountOptions, options?: EngineReadOptions): Promise<number>;
+    aggregate(object: string, query: EngineAggregateOptions, options?: EngineReadOptions): Promise<any[]>;
     /**
      * Run raw driver-specific commands (SQL for SqlDriver, REST for RestDriver, …).
      *

package/dist/index.js

@@ -2832,6 +2832,13 @@ function normaliseVersionToken(v) {
   }
   return s;
 }
+var CLONE_STRIP_FIELDS = [
+  "id",
+  "created_at",
+  "created_by",
+  "updated_at",
+  "updated_by"
+];
 var SERVICE_CONFIG = {
   auth: { route: "/api/v1/auth", plugin: "plugin-auth" },
   automation: { route: "/api/v1/automation", plugin: "plugin-automation" },
@@ -4087,6 +4094,68 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       record: result
     };
   }
+  /**
+   * Clone a record — read the source, drop engine-owned columns, and
+   * insert a fresh copy. Gated by the object's `enable.clone` capability
+   * (default `true`; only an explicit `enable.clone === false` disables it).
+   *
+   * Shallow by design: it duplicates the record's own scalar/business field
+   * values, not its related child records. The insert path re-stamps audit
+   * columns, regenerates `autonumber` fields, and recomputes derived
+   * (`formula`/`summary`) fields, so the copy is a valid new row rather than
+   * a byte-identical twin. Caller-supplied `overrides` are applied last and
+   * win over the copied values — the natural place to set a new `name`,
+   * clear a unique field, or reset status before insert.
+   */
+  async cloneData(request) {
+    const schema = this.engine.registry.getObject(request.object);
+    if (!schema) {
+      const err = new Error(`Object '${request.object}' not found`);
+      err.code = "OBJECT_NOT_FOUND";
+      err.status = 404;
+      err.object = request.object;
+      throw err;
+    }
+    if (schema.enable?.clone === false) {
+      const err = new Error(`Cloning is disabled for object '${request.object}'`);
+      err.code = "CLONE_DISABLED";
+      err.status = 403;
+      err.object = request.object;
+      throw err;
+    }
+    const ctx = request.context;
+    const ctxOpt = ctx !== void 0 ? { context: ctx } : void 0;
+    const source = await this.engine.findOne(
+      request.object,
+      { where: { id: request.id }, ...ctxOpt }
+    );
+    if (!source) {
+      const err = new Error(`Record ${request.id} not found in ${request.object}`);
+      err.code = "RECORD_NOT_FOUND";
+      err.status = 404;
+      err.object = request.object;
+      throw err;
+    }
+    const data = { ...source };
+    for (const f of CLONE_STRIP_FIELDS) delete data[f];
+    const fields = schema.fields || {};
+    for (const [name, def] of Object.entries(fields)) {
+      if (!def) continue;
+      if (def.system === true || def.type === "autonumber" || def.type === "formula" || def.type === "summary") {
+        delete data[name];
+      }
+    }
+    if (request.overrides && typeof request.overrides === "object") {
+      Object.assign(data, request.overrides);
+    }
+    const result = await this.engine.insert(request.object, data, ctxOpt);
+    return {
+      object: request.object,
+      id: result.id,
+      sourceId: request.id,
+      record: result
+    };
+  }
   async updateData(request) {
     await this.assertVersionMatch(request.object, request.id, request.expectedVersion, request.context);
     const opts = { where: { id: request.id } };
@@ -7281,6 +7350,11 @@ function applyFormulaPlan(plan, records) {
     }
   }
 }
+function mergeReadContext(fromQuery, fromOptions) {
+  if (fromOptions == null) return fromQuery;
+  if (fromQuery == null) return fromOptions;
+  return { ...fromQuery, ...fromOptions };
+}
 function resolveMetadataItemName(key, item) {
   if (!item) return void 0;
   if (item.name) return item.name;
@@ -8594,7 +8668,7 @@ var _ObjectQL = class _ObjectQL {
   // ============================================
   // Data Access Methods (IDataEngine Interface)
   // ============================================
-  async find(object, query) {
+  async find(object, query, options) {
     object = this.resolveObjectName(object);
     this.logger.debug("Find operation starting", { object, query });
     const driver = this.getDriver(object);
@@ -8623,7 +8697,7 @@ var _ObjectQL = class _ObjectQL {
       operation: "find",
       ast,
       options: query,
-      context: query?.context
+      context: mergeReadContext(query?.context, options?.context)
     };
     await this.executeWithMiddleware(opCtx, async () => {
       const hookContext = {
@@ -8655,7 +8729,7 @@ var _ObjectQL = class _ObjectQL {
     });
     return opCtx.result;
   }
-  async findOne(objectName, query) {
+  async findOne(objectName, query, options) {
     objectName = this.resolveObjectName(objectName);
     this.logger.debug("FindOne operation", { objectName });
     const driver = this.getDriver(objectName);
@@ -8678,7 +8752,7 @@ var _ObjectQL = class _ObjectQL {
       operation: "findOne",
       ast,
       options: query,
-      context: query?.context
+      context: mergeReadContext(query?.context, options?.context)
     };
     await this.executeWithMiddleware(opCtx, async () => {
       const findOneOpts = this.buildDriverOptions(opCtx.context);
@@ -9024,14 +9098,14 @@ var _ObjectQL = class _ObjectQL {
     });
     return opCtx.result;
   }
-  async count(object, query) {
+  async count(object, query, options) {
     object = this.resolveObjectName(object);
     const driver = this.getDriver(object);
     const opCtx = {
       object,
       operation: "count",
       options: query,
-      context: query?.context
+      context: mergeReadContext(query?.context, options?.context)
     };
     await this.executeWithMiddleware(opCtx, async () => {
       const countOpts = this.buildDriverOptions(opCtx.context);
@@ -9044,7 +9118,7 @@ var _ObjectQL = class _ObjectQL {
     });
     return opCtx.result;
   }
-  async aggregate(object, query) {
+  async aggregate(object, query, options) {
     object = this.resolveObjectName(object);
     const driver = this.getDriver(object);
     this.logger.debug(`Aggregate on ${object} using ${driver.name}`, query);
@@ -9052,7 +9126,7 @@ var _ObjectQL = class _ObjectQL {
       object,
       operation: "aggregate",
       options: query,
-      context: query?.context
+      context: mergeReadContext(query?.context, options?.context)
     };
     await this.executeWithMiddleware(opCtx, async () => {
       const ast = {