forge-sql-orm 2.1.13 → 2.1.14

package/dist/utils/metadataContextUtils.js

@@ -10,9 +10,7 @@ async function saveMetaDataToContext(metadata) {
     const context = exports.metadataQueryContext.getStore();
     if (context) {
         context.printQueriesWithPlan = async () => {
-            if (process.env.NODE_ENV !== "test") {
-                await new Promise((r) => setTimeout(r, 200));
-            }
+            await new Promise((r) => setTimeout(r, 200));
             await (0, sqlUtils_1.printQueriesWithPlan)(context.forgeSQLORM, Date.now() - context.beginTime.getTime());
         };
         if (metadata) {

package/dist/utils/metadataContextUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"metadataContextUtils.js","sourceRoot":"","sources":["../../src/utils/metadataContextUtils.ts"],"names":[],"mappings":";;;AAcA,sDAeC;AAED,gDAEC;AAjCD,uDAAqD;AAGrD,yCAAkD;AASrC,QAAA,oBAAoB,GAAG,IAAI,oCAAiB,EAAwB,CAAC;AAE3E,KAAK,UAAU,qBAAqB,CAAC,QAA2B;IACrE,MAAM,OAAO,GAAG,4BAAoB,CAAC,QAAQ,EAAE,CAAC;IAChD,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CAAC,oBAAoB,GAAG,KAAK,IAAI,EAAE;YACxC,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;gBACpC,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YAC/C,CAAC;YACD,MAAM,IAAA,+BAAoB,EAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5F,CAAC,CAAC;QACF,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,CAAC,iBAAiB,IAAI,QAAQ,CAAC,YAAY,CAAC;YACnD,OAAO,CAAC,oBAAoB,IAAI,QAAQ,CAAC,eAAe,CAAC;QAC3D,CAAC;QACD,6BAA6B;IAC/B,CAAC;AACH,CAAC;AAEM,KAAK,UAAU,kBAAkB;IACtC,OAAO,4BAAoB,CAAC,QAAQ,EAAE,CAAC;AACzC,CAAC"}
+{"version":3,"file":"metadataContextUtils.js","sourceRoot":"","sources":["../../src/utils/metadataContextUtils.ts"],"names":[],"mappings":";;;AAcA,sDAaC;AAED,gDAEC;AA/BD,uDAAqD;AAGrD,yCAAkD;AASrC,QAAA,oBAAoB,GAAG,IAAI,oCAAiB,EAAwB,CAAC;AAE3E,KAAK,UAAU,qBAAqB,CAAC,QAA2B;IACrE,MAAM,OAAO,GAAG,4BAAoB,CAAC,QAAQ,EAAE,CAAC;IAChD,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CAAC,oBAAoB,GAAG,KAAK,IAAI,EAAE;YACxC,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YAC7C,MAAM,IAAA,+BAAoB,EAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5F,CAAC,CAAC;QACF,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,CAAC,iBAAiB,IAAI,QAAQ,CAAC,YAAY,CAAC;YACnD,OAAO,CAAC,oBAAoB,IAAI,QAAQ,CAAC,eAAe,CAAC;QAC3D,CAAC;QACD,6BAA6B;IAC/B,CAAC;AACH,CAAC;AAEM,KAAK,UAAU,kBAAkB;IACtC,OAAO,4BAAoB,CAAC,QAAQ,EAAE,CAAC;AACzC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-sql-orm",
-  "version": "2.1.13",
+  "version": "2.1.14",
   "description": "Drizzle ORM integration for Atlassian @forge/sql. Provides a custom driver, schema migration, two levels of caching (local and global via @forge/kvs), optimistic locking, and query analysis.",
   "main": "dist/index.js",
   "homepage": "https://github.com/vzakharchenko/forge-sql-orm#readme",
@@ -29,8 +29,8 @@
     "@types/node": "^24.10.1",
     "@typescript-eslint/eslint-plugin": "^8.47.0",
     "@typescript-eslint/parser": "^8.47.0",
-    "@vitest/coverage-v8": "^4.0.12",
-    "@vitest/ui": "^4.0.12",
+    "@vitest/coverage-v8": "^4.0.13",
+    "@vitest/ui": "^4.0.13",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
@@ -42,7 +42,7 @@
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3",
     "uuid": "^13.0.0",
-    "vitest": "^4.0.12"
+    "vitest": "^4.0.13"
   },
   "license": "MIT",
   "author": "Vasyl Zakharchenko",
@@ -74,10 +74,11 @@
     "drizzle-orm": "^0.44.7"
   },
   "optionalDependencies": {
-    "@forge/kvs": "^1.0.8"
+    "@forge/kvs": "^1.2.0"
   },
   "dependencies": {
-    "luxon": "^3.7.2"
+    "luxon": "^3.7.2",
+    "node-sql-parser": "^5.3.13"
   },
   "lint-staged": {
     "*.{ts,tsx,css,scss,md}": [

package/src/core/ForgeSQLORM.ts

@@ -5,6 +5,7 @@ import {
   ForgeSqlOrmOptions,
   SchemaAnalyzeForgeSql,
   SchemaSqlForgeSql,
+  RovoIntegration,
 } from "./ForgeSQLQueryBuilder";
 import { ForgeSQLSelectOperations } from "./ForgeSQLSelectOperations";
 import {
@@ -41,6 +42,7 @@ import { WithSubquery } from "drizzle-orm/subquery";
 import { getLastestMetadata, metadataQueryContext } from "../utils/metadataContextUtils";
 import { operationTypeQueryContext } from "../utils/requestTypeContextUtils";
 import type { MySqlQueryResultKind } from "drizzle-orm/mysql-core/session";
+import { Rovo } from "./Rovo";
 
 /**
  * Implementation of ForgeSQLORM that uses Drizzle ORM for query building.
@@ -827,6 +829,37 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
   with(...queries: WithSubquery[]) {
     return this.drizzle.with(...queries);
   }
+
+  /**
+   * Provides access to Rovo integration - a secure pattern for natural-language analytics.
+   *
+   * Rovo enables secure execution of dynamic SQL queries with comprehensive security validations:
+   * - Only SELECT queries are allowed
+   * - Queries are restricted to a single table
+   * - JOINs, subqueries, and window functions are blocked
+   * - Row-Level Security (RLS) support for data isolation
+   *
+   * @returns {RovoIntegration} Rovo integration instance for secure dynamic queries
+   *
+   * @example
+   * ```typescript
+   * const rovo = forgeSQL.rovo();
+   * const settings = await rovo.rovoSettingBuilder(usersTable, accountId)
+   *   .useRLS()
+   *   .addRlsColumn(usersTable.id)
+   *   .addRlsWherePart((alias) => `${alias}.id = '${accountId}'`)
+   *   .finish()
+   *   .build();
+   *
+   * const result = await rovo.dynamicIsolatedQuery(
+   *   "SELECT id, name FROM users WHERE status = 'active'",
+   *   settings
+   * );
+   * ```
+   */
+  rovo(): RovoIntegration {
+    return new Rovo(this, this.options);
+  }
 }
 
 /**
@@ -1390,6 +1423,37 @@ class ForgeSQLORM implements ForgeSqlOperation {
   with(...queries: WithSubquery[]) {
     return this.ormInstance.getDrizzleQueryBuilder().with(...queries);
   }
+
+  /**
+   * Provides access to Rovo integration - a secure pattern for natural-language analytics.
+   *
+   * Rovo enables secure execution of dynamic SQL queries with comprehensive security validations:
+   * - Only SELECT queries are allowed
+   * - Queries are restricted to a single table
+   * - JOINs, subqueries, and window functions are blocked
+   * - Row-Level Security (RLS) support for data isolation
+   *
+   * @returns {RovoIntegration} Rovo integration instance for secure dynamic queries
+   *
+   * @example
+   * ```typescript
+   * const rovo = forgeSQL.rovo();
+   * const settings = await rovo.rovoSettingBuilder(usersTable, accountId)
+   *   .useRLS()
+   *   .addRlsColumn(usersTable.id)
+   *   .addRlsWherePart((alias) => `${alias}.id = '${accountId}'`)
+   *   .finish()
+   *   .build();
+   *
+   * const result = await rovo.dynamicIsolatedQuery(
+   *   "SELECT id, name FROM users WHERE status = 'active'",
+   *   settings
+   * );
+   * ```
+   */
+  rovo(): RovoIntegration {
+    return this.ormInstance.rovo();
+  }
 }
 
 export default ForgeSQLORM;

package/src/core/ForgeSQLQueryBuilder.ts

@@ -1,4 +1,4 @@
-import { UpdateQueryResponse } from "@forge/sql";
+import { Result, UpdateQueryResponse } from "@forge/sql";
 import { SqlParameters } from "@forge/sql/out/sql-statement";
 import {
   AnyMySqlSelectQueryBuilder,
@@ -56,6 +56,7 @@ import { SQLWrapper } from "drizzle-orm/sql/sql";
 import type { MySqlQueryResultKind } from "drizzle-orm/mysql-core/session";
 import type { WithBuilder } from "drizzle-orm/mysql-core/subquery";
 import { WithSubquery } from "drizzle-orm/subquery";
+import { MySqlColumn } from "drizzle-orm/mysql-core";
 
 /**
  * Core interface for ForgeSQL operations.
@@ -120,6 +121,35 @@ export interface ForgeSqlOperation extends QueryBuilderForgeSql {
    * @returns {ForgeSQLCacheOperations} Interface for executing versioned SQL operations with cache management
    */
   modifyWithVersioningAndEvictCache(): ForgeSQLCacheOperations;
+
+  /**
+   * Provides access to Rovo integration - a secure pattern for natural-language analytics.
+   *
+   * Rovo enables secure execution of dynamic SQL queries with comprehensive security validations:
+   * - Only SELECT queries are allowed
+   * - Queries are restricted to a single table
+   * - JOINs, subqueries, and window functions are blocked
+   * - Row-Level Security (RLS) support for data isolation
+   *
+   * @returns {RovoIntegration} Rovo integration instance for secure dynamic queries
+   *
+   * @example
+   * ```typescript
+   * const rovo = forgeSQL.rovo();
+   * const settings = await rovo.rovoSettingBuilder(usersTable, accountId)
+   *   .useRLS()
+   *   .addRlsColumn(usersTable.id)
+   *   .addRlsWherePart((alias) => `${alias}.id = '${accountId}'`)
+   *   .finish()
+   *   .build();
+   *
+   * const result = await rovo.dynamicIsolatedQuery(
+   *   "SELECT id, name FROM users WHERE status = 'active'",
+   *   settings
+   * );
+   * ```
+   */
+  rovo(): RovoIntegration;
 }
 
 /**
@@ -998,6 +1028,175 @@ export interface SchemaSqlForgeSql {
   executeRawUpdateSQL(query: string, params?: unknown[]): Promise<UpdateQueryResponse>;
 }
 
+/**
+ * Interface for Rovo integration settings.
+ * Defines configuration for secure dynamic SQL query execution.
+ *
+ * @interface RovoIntegrationSetting
+ */
+export interface RovoIntegrationSetting {
+  /**
+   * Gets the account ID of the active user.
+   *
+   * @returns {string} The account ID of the active user
+   */
+  getActiveUser(): string;
+
+  /**
+   * Gets the context parameters for query substitution.
+   *
+   * @returns {Record<string, string>} Map of parameter names to their values
+   */
+  getParameters(): Record<string, string>;
+
+  /**
+   * Gets the name of the table to query.
+   *
+   * @returns {string} The table name
+   */
+  getTableName(): string;
+
+  /**
+   * Checks if Row-Level Security is enabled.
+   *
+   * @returns {boolean} True if RLS is enabled, false otherwise
+   */
+  isUseRLS(): boolean;
+
+  /**
+   * Generates the WHERE clause for Row-Level Security filtering.
+   *
+   * @param {string} alias - The table alias to use in the WHERE clause
+   * @returns {string} SQL WHERE clause condition for RLS filtering
+   */
+  userScopeWhere(alias: string): string;
+
+  /**
+   * Gets the list of field names required for RLS validation.
+   *
+   * @returns {string[]} Array of field names that must be present in SELECT clause for RLS
+   */
+  userScopeFields(): string[];
+}
+
+/**
+ * Interface for configuring Row-Level Security (RLS) settings.
+ * Provides a fluent API for setting up RLS conditions, required columns, and WHERE clauses.
+ *
+ * @interface RlsSettings
+ */
+export interface RlsSettings {
+  /**
+   * Sets a conditional function to determine if RLS should be applied.
+   *
+   * @param {() => Promise<boolean>} condition - Async function that returns true if RLS should be enabled
+   * @returns {RlsSettings} This builder instance for method chaining
+   */
+  addRlsCondition(condition: () => Promise<boolean>): RlsSettings;
+
+  /**
+   * Adds a column name that must be present in the SELECT clause for RLS validation.
+   *
+   * @param {string} columnName - The name of the column to require
+   * @returns {RlsSettings} This builder instance for method chaining
+   */
+  addRlsColumnName(columnName: string): RlsSettings;
+
+  /**
+   * Adds a Drizzle column that must be present in the SELECT clause for RLS validation.
+   *
+   * @param {MySqlColumn} column - The Drizzle column object
+   * @returns {RlsSettings} This builder instance for method chaining
+   */
+  addRlsColumn(columnName: MySqlColumn): RlsSettings;
+
+  /**
+   * Sets the WHERE clause function for RLS filtering.
+   *
+   * @param {(alias: string) => string} wherePart - Function that generates WHERE clause
+   * @returns {RlsSettings} This builder instance for method chaining
+   */
+  addRlsWherePart(wherePart: (alias: string) => string): RlsSettings;
+
+  /**
+   * Finishes RLS configuration and returns to the settings builder.
+   *
+   * @returns {RovoIntegrationSettingCreator} The parent settings builder
+   */
+  finish(): RovoIntegrationSettingCreator;
+}
+
+/**
+ * Interface for building Rovo integration settings.
+ * Provides a fluent API for configuring query settings including context parameters and RLS.
+ *
+ * @interface RovoIntegrationSettingCreator
+ */
+export interface RovoIntegrationSettingCreator {
+  /**
+   * Adds a context parameter for query substitution.
+   *
+   * @param {string} parameterName - The parameter name to replace in the query
+   * @param {string} value - The value to substitute for the parameter
+   * @returns {RovoIntegrationSettingCreator} This builder instance for method chaining
+   */
+  addContextParameter(parameterName: string, value: string): RovoIntegrationSettingCreator;
+
+  /**
+   * Enables Row-Level Security (RLS) for the query.
+   *
+   * @returns {RlsSettings} RLS settings builder for configuring security options
+   */
+  useRLS(): RlsSettings;
+
+  /**
+   * Builds and returns the RovoIntegrationSetting instance.
+   *
+   * @returns {Promise<RovoIntegrationSetting>} The configured RovoIntegrationSetting instance
+   */
+  build(): Promise<RovoIntegrationSetting>;
+}
+
+/**
+ * Interface for Rovo integration - a secure pattern for natural-language analytics.
+ *
+ * Rovo provides secure execution of dynamic SQL queries with comprehensive security validations.
+ *
+ * @interface RovoIntegration
+ */
+export interface RovoIntegration {
+  /**
+   * Creates a settings builder for Rovo queries using a raw table name.
+   *
+   * @param {string} tableName - The name of the table to query
+   * @param {string} accountId - The account ID of the active user
+   * @returns {RovoIntegrationSettingCreator} Builder for configuring Rovo query settings
+   */
+  rovoRawSettingBuilder(tableName: string, accountId: string): RovoIntegrationSettingCreator;
+
+  /**
+   * Creates a settings builder for Rovo queries using a Drizzle table object.
+   *
+   * @param {AnyMySqlTable} table - The Drizzle table object
+   * @param {string} accountId - The account ID of the active user
+   * @returns {RovoIntegrationSettingCreator} Builder for configuring Rovo query settings
+   */
+  rovoSettingBuilder(table: AnyMySqlTable, accountId: string): RovoIntegrationSettingCreator;
+
+  /**
+   * Executes a dynamic SQL query with comprehensive security validations.
+   *
+   * @param {string} dynamicSql - The SQL query to execute (must be a SELECT statement)
+   * @param {RovoIntegrationSetting} settings - Configuration settings for the query
+   * @returns {Promise<Result<unknown>>} Query execution result with metadata
+   * @throws {Error} If the query violates security restrictions
+   */
+  dynamicIsolatedQuery(
+    dynamicSql: string,
+    settings: RovoIntegrationSetting,
+  ): Promise<Result<unknown>>;
+}
+
 /**
  * Interface for version field metadata.
  * Defines the configuration for optimistic locking version fields.