forge-sql-orm 2.0.30 → 2.1.1

package/dist/lib/drizzle/extensions/additionalActions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"additionalActions.d.ts","sourceRoot":"","sources":["../../../../src/lib/drizzle/extensions/additionalActions.ts"],"names":[],"mappings":"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"}

package/dist/utils/cacheContextUtils.d.ts

@@ -0,0 +1,123 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { AnyMySqlSelectQueryBuilder, AnyMySqlTable } from "drizzle-orm/mysql-core";
+import { ForgeSqlOrmOptions } from "../core/ForgeSQLQueryBuilder";
+import { MySqlSelectDynamic } from "drizzle-orm/mysql-core/query-builders/select.types";
+/**
+ * Interface representing the cache application context.
+ * Stores information about tables that are being processed within a cache context.
+ */
+export interface CacheApplicationContext {
+    /** Set of table names (in lowercase) that are being processed within the cache context */
+    tables: Set<string>;
+}
+/**
+ * Interface representing the local cache application context.
+ * Stores cached query results in memory for the duration of a local cache context.
+ *
+ * @interface LocalCacheApplicationContext
+ */
+export interface LocalCacheApplicationContext {
+    /**
+     * Cache object mapping query hash keys to cached results
+     * @property {Record<string, {sql: string, data: unknown[]}>} cache - Map of query keys to cached data
+     */
+    cache: Record<string, {
+        sql: string;
+        data: unknown[];
+    }>;
+}
+/**
+ * AsyncLocalStorage instance for managing cache context across async operations.
+ * This allows tracking which tables are being processed within a cache context
+ * without explicitly passing context through function parameters.
+ */
+export declare const cacheApplicationContext: AsyncLocalStorage<CacheApplicationContext>;
+/**
+ * AsyncLocalStorage instance for managing local cache context across async operations.
+ * This allows storing and retrieving cached query results within a local cache context
+ * without explicitly passing context through function parameters.
+ */
+export declare const localCacheApplicationContext: AsyncLocalStorage<LocalCacheApplicationContext>;
+/**
+ * Saves a table name to the current cache context if one exists.
+ * This function is used to track which tables are being processed within
+ * a cache context for proper cache invalidation.
+ *
+ * @param table - The Drizzle table schema to track
+ * @returns Promise that resolves when the table is saved to context
+ *
+ * @example
+ * ```typescript
+ * await saveTableIfInsideCacheContext(usersTable);
+ * ```
+ */
+export declare function saveTableIfInsideCacheContext<T extends AnyMySqlTable>(table: T): Promise<void>;
+/**
+ * Saves a query result to the local cache context.
+ * This function stores query results in memory for the duration of the local cache context.
+ *
+ * @param query - The Drizzle query to cache
+ * @param rows - The query result data to cache
+ * @returns Promise that resolves when the data is saved to local cache
+ *
+ * @example
+ * ```typescript
+ * const query = db.select({ id: users.id, name: users.name }).from(users);
+ * const results = await query.execute();
+ * await saveQueryLocalCacheQuery(query, results);
+ * ```
+ */
+export declare function saveQueryLocalCacheQuery<T extends MySqlSelectDynamic<AnyMySqlSelectQueryBuilder>>(query: T, rows: unknown[]): Promise<void>;
+/**
+ * Retrieves a query result from the local cache context.
+ * This function checks if a query result is already cached in memory.
+ *
+ * @param query - The Drizzle query to check for cached results
+ * @returns Promise that resolves to cached data if found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const query = db.select({ id: users.id, name: users.name }).from(users);
+ * const cachedResult = await getQueryLocalCacheQuery(query);
+ * if (cachedResult) {
+ *   return cachedResult; // Use cached data
+ * }
+ * // Execute query and cache result
+ * ```
+ */
+export declare function getQueryLocalCacheQuery<T extends MySqlSelectDynamic<AnyMySqlSelectQueryBuilder>>(query: T): Promise<unknown[] | undefined>;
+/**
+ * Evicts cached queries from the local cache context that involve the specified table.
+ * This function removes cached query results that contain the given table name.
+ *
+ * @param table - The Drizzle table schema to evict cache for
+ * @param options - ForgeSQL ORM options containing cache configuration
+ * @returns Promise that resolves when cache eviction is complete
+ *
+ * @example
+ * ```typescript
+ * // After inserting/updating/deleting from users table
+ * await evictLocalCacheQuery(usersTable, forgeSqlOptions);
+ * // All cached queries involving users table are now removed
+ * ```
+ */
+export declare function evictLocalCacheQuery<T extends AnyMySqlTable>(table: T, options: ForgeSqlOrmOptions): Promise<void>;
+/**
+ * Checks if the given SQL query contains any tables that are currently being processed
+ * within a cache context. This is used to determine if cache should be bypassed
+ * for queries that affect tables being modified within the context.
+ *
+ * @param sql - The SQL query string to check
+ * @param options - ForgeSQL ORM options containing cache configuration
+ * @returns Promise that resolves to true if the SQL contains tables in cache context
+ *
+ * @example
+ * ```typescript
+ * const shouldBypassCache = await isTableContainsTableInCacheContext(
+ *   "SELECT * FROM users WHERE id = 1",
+ *   forgeSqlOptions
+ * );
+ * ```
+ */
+export declare function isTableContainsTableInCacheContext(sql: string, options: ForgeSqlOrmOptions): Promise<boolean>;
+//# sourceMappingURL=cacheContextUtils.d.ts.map

package/dist/utils/cacheContextUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheContextUtils.d.ts","sourceRoot":"","sources":["../../src/utils/cacheContextUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,0BAA0B,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oDAAoD,CAAC;AAIxF;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,0FAA0F;IAC1F,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,KAAK,EAAE,MAAM,CACX,MAAM,EACN;QACE,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,OAAO,EAAE,CAAC;KACjB,CACF,CAAC;CACH;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,4CAAmD,CAAC;AAExF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,iDAAwD,CAAC;AAElG;;;;;;;;;;;;GAYG;AACH,wBAAsB,6BAA6B,CAAC,CAAC,SAAS,aAAa,EACzE,KAAK,EAAE,CAAC,GACP,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,wBAAwB,CAC5C,CAAC,SAAS,kBAAkB,CAAC,0BAA0B,CAAC,EACxD,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAa1C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,CAAC,SAAS,kBAAkB,CAAC,0BAA0B,CAAC,EACxD,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,CAa1C;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,SAAS,aAAa,EAChE,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kCAAkC,CACtD,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAalB"}

package/dist/utils/cacheUtils.d.ts

@@ -0,0 +1,56 @@
+import { Query } from "drizzle-orm";
+import { AnyMySqlTable } from "drizzle-orm/mysql-core";
+import { ForgeSqlOrmOptions } from "../core/ForgeSQLQueryBuilder";
+/**
+ * Generates a hash key for a query based on its SQL and parameters.
+ *
+ * @param query - The Drizzle query object
+ * @returns 32-character hexadecimal hash
+ */
+export declare function hashKey(query: Query): string;
+/**
+ * Clears cache for a specific table.
+ * Uses cache context if available, otherwise clears immediately.
+ *
+ * @param schema - The table schema to clear cache for
+ * @param options - ForgeSQL ORM options
+ */
+export declare function clearCache<T extends AnyMySqlTable>(schema: T, options: ForgeSqlOrmOptions): Promise<void>;
+/**
+ * Clears cache for multiple tables with retry logic and performance logging.
+ *
+ * @param tables - Array of table names to clear cache for
+ * @param options - ForgeSQL ORM options
+ * @returns Promise that resolves when cache clearing is complete
+ */
+export declare function clearTablesCache(tables: string[], options: ForgeSqlOrmOptions): Promise<void>;
+/**
+ * Clears expired cache entries with retry logic and performance logging.
+ *
+ * @param options - ForgeSQL ORM options
+ * @returns Promise that resolves when expired cache clearing is complete
+ */
+export declare function clearExpiredCache(options: ForgeSqlOrmOptions): Promise<void>;
+/**
+ * Retrieves data from cache if it exists and is not expired.
+ *
+ * @param query - Query object with toSQL method
+ * @param options - ForgeSQL ORM options
+ * @returns Cached data if found and valid, undefined otherwise
+ */
+export declare function getFromCache<T>(query: {
+    toSQL: () => Query;
+}, options: ForgeSqlOrmOptions): Promise<T | undefined>;
+/**
+ * Stores query results in cache with specified TTL.
+ *
+ * @param query - Query object with toSQL method
+ * @param options - ForgeSQL ORM options
+ * @param results - Data to cache
+ * @param cacheTtl - Time to live in seconds
+ * @returns Promise that resolves when data is stored in cache
+ */
+export declare function setCacheResult(query: {
+    toSQL: () => Query;
+}, options: ForgeSqlOrmOptions, results: unknown, cacheTtl: number): Promise<void>;
+//# sourceMappingURL=cacheUtils.d.ts.map

package/dist/utils/cacheUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheUtils.d.ts","sourceRoot":"","sources":["../../src/utils/cacheUtils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AA2ClE;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAK5C;AA+JD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,aAAa,EACtD,MAAM,EAAE,CAAC,EACT,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAmBf;AACD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBlF;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,KAAK,CAAA;CAAE,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAwCxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,KAAK,CAAA;CAAE,EAC7B,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA2Cf"}

package/dist/utils/sqlUtils.d.ts

@@ -34,6 +34,14 @@ export interface MetadataInfo {
  * @returns Date object
  */
 export declare const parseDateTime: (value: string | Date, format: string) => Date;
+/**
+ * Helper function to validate and format a date-like value using Luxon DateTime.
+ * @param value - Date object, ISO/RFC2822/SQL/HTTP string, or timestamp (number|string).
+ * @param format - DateTime format string (Luxon format tokens).
+ * @returns Formatted date string.
+ * @throws Error if value cannot be parsed as a valid date.
+ */
+export declare function formatDateTime(value: Date | string | number, format: string): string;
 /**
  * Gets primary keys from the schema.
  * @template T - The type of the table schema

package/dist/utils/sqlUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlUtils.d.ts","sourceRoot":"","sources":["../../src/utils/sqlUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAA0C,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,aAAa,EAAqB,MAAM,8BAA8B,CAAC;AAEhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAC;AACnF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AAIzF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACnC,8BAA8B;IAC9B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,yCAAyC;IACzC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,oCAAoC;IACpC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,oCAAoC;IACpC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,0CAA0C;IAC1C,iBAAiB,EAAE,uBAAuB,EAAE,CAAC;IAC7C,kCAAkC;IAClC,MAAM,EAAE,GAAG,EAAE,CAAC;CACf;AAUD;;;;;GAKG;AAEH,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,GAAG,IAAI,EAAE,QAAQ,MAAM,KAAG,IAyBpE,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAkCvF;AA0DD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAoEnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,CAAC,EAAE;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC9C,MAAM,EAAE,CAiBV;AAED,KAAK,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAuBhD,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,GAAG,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,GAAG,EACX,QAAQ,EAAE,cAAc,GACvB,GAAG,CAmBL;AACD,wBAAgB,wBAAwB,CAAC,UAAU,SAAS,cAAc,EACxE,MAAM,EAAE,UAAU,GACjB;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,CAUtD;AAsED,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,UAAU,EACpD,IAAI,EAAE,CAAC,EAAE,EACT,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAClC,CAAC,EAAE,CAUL;AAoCD,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED,wBAAgB,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEpD"}
+{"version":3,"file":"sqlUtils.d.ts","sourceRoot":"","sources":["../../src/utils/sqlUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAA0C,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,aAAa,EAAqB,MAAM,8BAA8B,CAAC;AAEhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAC;AACnF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAC;AAIzF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACnC,8BAA8B;IAC9B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,yCAAyC;IACzC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,oCAAoC;IACpC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,oCAAoC;IACpC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,0CAA0C;IAC1C,iBAAiB,EAAE,uBAAuB,EAAE,CAAC;IAC7C,kCAAkC;IAClC,MAAM,EAAE,GAAG,EAAE,CAAC;CACf;AAUD;;;;;GAKG;AAEH,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,GAAG,IAAI,EAAE,QAAQ,MAAM,KAAG,IAyBpE,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAiCpF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAkCvF;AA0DD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAoEnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,CAAC,EAAE;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC9C,MAAM,EAAE,CAiBV;AAED,KAAK,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAuBhD,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,GAAG,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,GAAG,EACX,QAAQ,EAAE,cAAc,GACvB,GAAG,CAmBL;AACD,wBAAgB,wBAAwB,CAAC,UAAU,SAAS,cAAc,EACxE,MAAM,EAAE,UAAU,GACjB;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,CAUtD;AAsED,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,UAAU,EACpD,IAAI,EAAE,CAAC,EAAE,EACT,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAClC,CAAC,EAAE,CAUL;AAoCD,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED,wBAAgB,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/webtriggers/clearCacheSchedulerTrigger.d.ts

@@ -0,0 +1,46 @@
+import { ForgeSqlOrmOptions } from "../core/ForgeSQLQueryBuilder";
+/**
+ * Scheduler trigger for clearing expired cache entries.
+ *
+ * This trigger should be configured as a Forge scheduler to automatically
+ * clean up expired cache entries based on their TTL (Time To Live).
+ *
+ * @param options - Optional ForgeSQL ORM configuration. If not provided,
+ *                  uses default cache settings with cacheEntityName: "cache"
+ * @returns Promise that resolves to HTTP response object
+ *
+ * @example
+ * ```typescript
+ * // In your index.ts
+ * import { clearCacheSchedulerTrigger } from "forge-sql-orm";
+ *
+ * export const clearCache = () => {
+ *   return clearCacheSchedulerTrigger({
+ *     cacheEntityName: "cache",
+ *     logRawSqlQuery: true
+ *   });
+ * };
+ * ```
+ *
+ * @example
+ * ```yaml
+ * # In manifest.yml
+ * scheduledTrigger:
+ *   - key: clear-cache-trigger
+ *     function: clearCache
+ *     interval: fiveMinute
+ *
+ * function:
+ *   - key: clearCache
+ *     handler: index.clearCache
+ * ```
+ */
+export declare const clearCacheSchedulerTrigger: (options?: ForgeSqlOrmOptions) => Promise<{
+    headers: {
+        "Content-Type": string[];
+    };
+    statusCode: number;
+    statusText: string;
+    body: string;
+}>;
+//# sourceMappingURL=clearCacheSchedulerTrigger.d.ts.map

package/dist/webtriggers/clearCacheSchedulerTrigger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clearCacheSchedulerTrigger.d.ts","sourceRoot":"","sources":["../../src/webtriggers/clearCacheSchedulerTrigger.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,0BAA0B,GAAU,UAAU,kBAAkB;;;;;;;EAuC5E,CAAC"}

package/dist/webtriggers/index.d.ts

@@ -2,6 +2,7 @@ export * from "./dropMigrationWebTrigger";
 export * from "./applyMigrationsWebTrigger";
 export * from "./fetchSchemaWebTrigger";
 export * from "./dropTablesMigrationWebTrigger";
+export * from "./clearCacheSchedulerTrigger";
 export interface TriggerResponse<BODY> {
     body?: BODY;
     headers?: Record<string, string[]>;

package/dist/webtriggers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/webtriggers/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAEhD,MAAM,WAAW,eAAe,CAAC,IAAI;IACnC,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,eAAe,GAAI,IAAI,EAAE,YAAY,MAAM,EAAE,MAAM,IAAI,KAAG,eAAe,CAAC,IAAI,CAc1F,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/webtriggers/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAE7C,MAAM,WAAW,eAAe,CAAC,IAAI;IACnC,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,eAAe,GAAI,IAAI,EAAE,YAAY,MAAM,EAAE,MAAM,IAAI,KAAG,eAAe,CAAC,IAAI,CAc1F,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "forge-sql-orm",
-  "version": "2.0.30",
-  "description": "Drizzle ORM integration for Forge-SQL in Atlassian Forge applications.",
+  "version": "2.1.1",
+  "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/ForgeSQLORM.js",
   "module": "dist/ForgeSQLORM.mjs",
   "types": "dist/index.d.ts",
@@ -32,23 +32,23 @@
     "database"
   ],
   "devDependencies": {
-    "@eslint/js": "^9.34.0",
+    "@eslint/js": "^9.35.0",
     "@types/luxon": "^3.7.1",
-    "@types/node": "^24.3.0",
-    "@typescript-eslint/eslint-plugin": "^8.41.0",
-    "@typescript-eslint/parser": "^8.41.0",
+    "@types/node": "^24.4.0",
+    "@typescript-eslint/eslint-plugin": "^8.43.0",
+    "@typescript-eslint/parser": "^8.43.0",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
-    "eslint": "^9.34.0",
+    "eslint": "^9.35.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-vitest": "^0.5.4",
-    "knip": "^5.63.0",
+    "knip": "^5.63.1",
     "prettier": "^3.6.2",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.2",
-    "uuid": "^11.1.0",
-    "vite": "^7.1.4",
+    "uuid": "^13.0.0",
+    "vite": "^7.1.5",
     "vitest": "^3.2.4"
   },
   "license": "MIT",
@@ -59,7 +59,7 @@
     "test:watch": "vitest --watch",
     "lint": "eslint src  --ext .ts,.tsx",
     "lint:fix": "eslint src --ext .ts,.tsx --fix",
-    "format": "prettier --write src examples",
+    "format": "prettier --write src examples __tests__",
     "clean": "rm -rf dist",
     "build": "npm run clean && vite build && npm run build:types",
     "build:types": "tsc --emitDeclarationOnly",
@@ -78,7 +78,10 @@
     "@forge/sql": "^3.0.5",
     "drizzle-orm": "^0.44.5"
   },
+  "optionalDependencies": {
+    "@forge/kvs": "^1.0.5"
+  },
   "dependencies": {
-    "luxon": "^3.7.1"
+    "luxon": "^3.7.2"
   }
 }

package/src/core/ForgeSQLAnalyseOperations.ts

@@ -6,7 +6,7 @@ import {
   SlowQueryNormalized,
 } from "./SystemTables";
 import { SqlParameters } from "@forge/sql/out/sql-statement";
-import { AnyMySqlTable } from "drizzle-orm/mysql-core/index";
+import { AnyMySqlTable } from "drizzle-orm/mysql-core";
 import { getTableName } from "drizzle-orm/table";
 import { DateTime } from "luxon";
 

package/src/core/ForgeSQLCacheOperations.ts

@@ -0,0 +1,195 @@
+import { MySqlSelectDynamic } from "drizzle-orm/mysql-core/query-builders/select.types";
+import { AnyMySqlSelectQueryBuilder, AnyMySqlTable } from "drizzle-orm/mysql-core";
+import { CacheForgeSQL, ForgeSqlOperation, ForgeSqlOrmOptions } from "./ForgeSQLQueryBuilder";
+import { InferInsertModel, Query, SQL } from "drizzle-orm";
+import { clearCache, getFromCache, setCacheResult, clearTablesCache } from "../utils/cacheUtils";
+import { getTableName } from "drizzle-orm/table";
+
+/**
+ * Implementation of cache operations for ForgeSQL ORM.
+ * Provides methods for cacheable database operations with automatic cache management.
+ *
+ * ⚠️ **IMPORTANT**: All modification methods in this class use optimistic locking/versioning
+ * through `modifyWithVersioning()` internally. This ensures data consistency and prevents
+ * concurrent modification conflicts.
+ */
+export class ForgeSQLCacheOperations implements CacheForgeSQL {
+  private readonly options: ForgeSqlOrmOptions;
+  private readonly forgeOperations: ForgeSqlOperation;
+
+  /**
+   * Creates a new instance of ForgeSQLCacheOperations.
+   *
+   * @param options - Configuration options for the ORM
+   * @param forgeOperations - The ForgeSQL operations instance
+   */
+  constructor(options: ForgeSqlOrmOptions, forgeOperations: ForgeSqlOperation) {
+    this.options = options;
+    this.forgeOperations = forgeOperations;
+  }
+
+  /**
+   * Evicts cache for multiple tables using Drizzle table objects.
+   *
+   * @param tables - Array of Drizzle table objects to clear cache for
+   * @returns Promise that resolves when cache eviction is complete
+   * @throws Error if cacheEntityName is not configured
+   */
+  async evictCacheEntities(tables: AnyMySqlTable[]): Promise<void> {
+    if (!this.options.cacheEntityName) {
+      throw new Error("cacheEntityName is not configured");
+    }
+    await this.evictCache(tables.map((t) => getTableName(t)));
+  }
+
+  /**
+   * Evicts cache for multiple tables by their names.
+   *
+   * @param tables - Array of table names to clear cache for
+   * @returns Promise that resolves when cache eviction is complete
+   * @throws Error if cacheEntityName is not configured
+   */
+  async evictCache(tables: string[]): Promise<void> {
+    if (!this.options.cacheEntityName) {
+      throw new Error("cacheEntityName is not configured");
+    }
+    await clearTablesCache(tables, this.options);
+  }
+
+  /**
+   * Inserts records with optimistic locking/versioning and automatically evicts cache.
+   *
+   * This method uses `modifyWithVersioning().insert()` internally, providing:
+   * - Automatic version field initialization
+   * - Optimistic locking support
+   * - Cache eviction after successful operation
+   *
+   * @param schema - The table schema
+   * @param models - Array of entities to insert
+   * @param updateIfExists - Whether to update existing records
+   * @returns Promise that resolves to the number of inserted rows
+   * @throws Error if cacheEntityName is not configured
+   * @throws Error if optimistic locking check fails
+   */
+  async insert<T extends AnyMySqlTable>(
+    schema: T,
+    models: InferInsertModel<T>[],
+    updateIfExists?: boolean,
+  ): Promise<number> {
+    this.validateCacheConfiguration();
+    const number = await this.forgeOperations
+      .modifyWithVersioning()
+      .insert(schema, models, updateIfExists);
+    await clearCache(schema, this.options);
+    return number;
+  }
+
+  /**
+   * Deletes a record by ID with optimistic locking/versioning and automatically evicts cache.
+   *
+   * This method uses `modifyWithVersioning().deleteById()` internally, providing:
+   * - Optimistic locking checks before deletion
+   * - Version field validation
+   * - Cache eviction after successful operation
+   *
+   * @param id - The ID of the record to delete
+   * @param schema - The table schema
+   * @returns Promise that resolves to the number of affected rows
+   * @throws Error if cacheEntityName is not configured
+   * @throws Error if optimistic locking check fails
+   */
+  async deleteById<T extends AnyMySqlTable>(id: unknown, schema: T): Promise<number> {
+    this.validateCacheConfiguration();
+    const number = await this.forgeOperations.modifyWithVersioning().deleteById(id, schema);
+    await clearCache(schema, this.options);
+    return number;
+  }
+
+  /**
+   * Updates a record by ID with optimistic locking/versioning and automatically evicts cache.
+   *
+   * This method uses `modifyWithVersioning().updateById()` internally, providing:
+   * - Optimistic locking checks before update
+   * - Version field incrementation
+   * - Cache eviction after successful operation
+   *
+   * @param entity - The entity with updated values (must include primary key)
+   * @param schema - The table schema
+   * @returns Promise that resolves to the number of affected rows
+   * @throws Error if cacheEntityName is not configured
+   * @throws Error if optimistic locking check fails
+   */
+  async updateById<T extends AnyMySqlTable>(
+    entity: Partial<InferInsertModel<T>>,
+    schema: T,
+  ): Promise<number> {
+    this.validateCacheConfiguration();
+    const number = await this.forgeOperations.modifyWithVersioning().updateById(entity, schema);
+    await clearCache(schema, this.options);
+    return number;
+  }
+
+  /**
+   * Updates fields based on conditions with optimistic locking/versioning and automatically evicts cache.
+   *
+   * This method uses `modifyWithVersioning().updateFields()` internally, providing:
+   * - Optimistic locking support (if version field is configured)
+   * - Version field validation and incrementation
+   * - Cache eviction after successful operation
+   *
+   * @param updateData - The data to update
+   * @param schema - The table schema
+   * @param where - Optional WHERE conditions
+   * @returns Promise that resolves to the number of affected rows
+   * @throws Error if cacheEntityName is not configured
+   * @throws Error if optimistic locking check fails
+   */
+  async updateFields<T extends AnyMySqlTable>(
+    updateData: Partial<InferInsertModel<T>>,
+    schema: T,
+    where?: SQL<unknown>,
+  ): Promise<number> {
+    this.validateCacheConfiguration();
+    const number = await this.forgeOperations
+      .modifyWithVersioning()
+      .updateFields(updateData, schema, where);
+    await clearCache(schema, this.options);
+    return number;
+  }
+
+  /**
+   * Executes a query with caching support.
+   * First checks cache, if not found executes query and stores result in cache.
+   *
+   * @param query - The Drizzle query to execute
+   * @param cacheTtl - Optional cache TTL override
+   * @returns Promise that resolves to the query results
+   * @throws Error if cacheEntityName is not configured
+   */
+  async executeQuery<T extends MySqlSelectDynamic<AnyMySqlSelectQueryBuilder>>(
+    query: T,
+    cacheTtl?: number,
+  ): Promise<Awaited<T>> {
+    this.validateCacheConfiguration();
+    const sqlQuery = query as { toSQL: () => Query };
+    const cacheResult = await getFromCache<Awaited<T>>(sqlQuery, this.options);
+    if (cacheResult) {
+      return cacheResult;
+    }
+    const results = await query;
+    await setCacheResult(sqlQuery, this.options, results, cacheTtl ?? this.options.cacheTTL ?? 60);
+    return results;
+  }
+
+  /**
+   * Validates that cache configuration is properly set up.
+   *
+   * @throws Error if cacheEntityName is not configured
+   * @private
+   */
+  private validateCacheConfiguration(): void {
+    if (!this.options.cacheEntityName) {
+      throw new Error("cacheEntityName is not configured");
+    }
+  }
+}