forge-sql-orm 2.1.0 → 2.1.2

package/dist/ForgeSQLORM.mjs

@@ -1,4 +1,4 @@
-import { isTable, sql, eq, and } from "drizzle-orm";
+import { isTable, sql, eq, and, getTableColumns } from "drizzle-orm";
 import { DateTime } from "luxon";
 import { isSQLWrapper } from "drizzle-orm/sql/sql";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -31,12 +31,34 @@ const parseDateTime = (value, format) => {
   return result;
 };
 function formatDateTime(value, format) {
-  const fromJSDate = DateTime.fromJSDate(value);
-  if (fromJSDate.isValid) {
-    return fromJSDate.toFormat(format);
+  let dt = null;
+  if (value instanceof Date) {
+    dt = DateTime.fromJSDate(value);
+  } else if (typeof value === "string") {
+    for (const parser of [
+      DateTime.fromISO,
+      DateTime.fromRFC2822,
+      DateTime.fromSQL,
+      DateTime.fromHTTP
+    ]) {
+      dt = parser(value);
+      if (dt.isValid) break;
+    }
+    if (!dt?.isValid) {
+      const parsed = Number(value);
+      if (!isNaN(parsed)) {
+        dt = DateTime.fromMillis(parsed);
+      }
+    }
+  } else if (typeof value === "number") {
+    dt = DateTime.fromMillis(value);
   } else {
+    throw new Error("Unsupported type");
+  }
+  if (!dt?.isValid) {
     throw new Error("Invalid Date");
   }
+  return dt.toFormat(format);
 }
 function getPrimaryKeys(table) {
   const { columns, primaryKeys } = getTableMetadata(table);
@@ -512,7 +534,7 @@ async function saveTableIfInsideCacheContext(table) {
     context.tables.add(tableName);
   }
 }
-async function saveQueryLocalCacheQuery(query, rows) {
+async function saveQueryLocalCacheQuery(query, rows, options) {
   const context = localCacheApplicationContext.getStore();
   if (context) {
     if (!context.cache) {
@@ -524,9 +546,15 @@ async function saveQueryLocalCacheQuery(query, rows) {
       sql: sql2.toSQL().sql.toLowerCase(),
       data: rows
     };
+    if (options.logRawSqlQuery) {
+      const q = sql2.toSQL();
+      console.log(
+        `[forge-sql-orm][local-cache][SAVE] Stored result in cache. sql="${q.sql}", params=${JSON.stringify(q.params)}`
+      );
+    }
   }
 }
-async function getQueryLocalCacheQuery(query) {
+async function getQueryLocalCacheQuery(query, options) {
   const context = localCacheApplicationContext.getStore();
   if (context) {
     if (!context.cache) {
@@ -535,6 +563,12 @@ async function getQueryLocalCacheQuery(query) {
     const sql2 = query;
     const key = hashKey(sql2.toSQL());
     if (context.cache[key] && context.cache[key].sql === sql2.toSQL().sql.toLowerCase()) {
+      if (options.logRawSqlQuery) {
+        const q = sql2.toSQL();
+        console.log(
+          `[forge-sql-orm][local-cache][HIT] Returned cached result. sql="${q.sql}", params=${JSON.stringify(q.params)}`
+        );
+      }
       return context.cache[key].data;
     }
   }
@@ -1024,11 +1058,21 @@ function createForgeDriverProxy(options, logRawSqlQuery) {
     return forgeDriver(modifiedQuery, params, method);
   };
 }
+const NON_CACHE_CLEARING_ERROR_CODES = ["VALIDATION_ERROR", "CONSTRAINT_ERROR"];
+const CACHE_CLEARING_ERROR_CODES = ["DEADLOCK", "LOCK_WAIT_TIMEOUT", "CONNECTION_ERROR"];
+const NON_CACHE_CLEARING_PATTERNS = [/validation/i, /constraint/i];
+const CACHE_CLEARING_PATTERNS = [/timeout/i, /connection/i];
 function shouldClearCacheOnError(error) {
-  if (error?.code === "VALIDATION_ERROR" || error?.code === "CONSTRAINT_ERROR" || error?.message && /validation/i.exec(error.message)) {
+  if (error?.code && NON_CACHE_CLEARING_ERROR_CODES.includes(error.code)) {
+    return false;
+  }
+  if (error?.message && NON_CACHE_CLEARING_PATTERNS.some((pattern) => pattern.test(error.message))) {
     return false;
   }
-  if (error?.code === "DEADLOCK" || error?.code === "LOCK_WAIT_TIMEOUT" || error?.code === "CONNECTION_ERROR" || error?.message && /timeout/i.exec(error.message) || error?.message && /connection/i.exec(error.message)) {
+  if (error?.code && CACHE_CLEARING_ERROR_CODES.includes(error.code)) {
+    return true;
+  }
+  if (error?.message && CACHE_CLEARING_PATTERNS.some((pattern) => pattern.test(error.message))) {
     return true;
   }
   return true;
@@ -1109,7 +1153,7 @@ function deleteAndEvictCacheBuilder(db, table, options, isCached) {
 }
 async function handleCachedQuery(target, options, cacheTtl, selections, aliasMap, onfulfilled, onrejected) {
   try {
-    const localCached = await getQueryLocalCacheQuery(target);
+    const localCached = await getQueryLocalCacheQuery(target, options);
     if (localCached) {
       return onfulfilled?.(localCached);
     }
@@ -1119,7 +1163,7 @@ async function handleCachedQuery(target, options, cacheTtl, selections, aliasMap
     }
     const rows = await target.execute();
     const transformed = applyFromDriverTransform(rows, selections, aliasMap);
-    await saveQueryLocalCacheQuery(target, transformed);
+    await saveQueryLocalCacheQuery(target, transformed, options);
     await setCacheResult(target, options, transformed, cacheTtl).catch((cacheError) => {
       console.warn("Cache set error:", cacheError);
     });
@@ -1128,15 +1172,15 @@ async function handleCachedQuery(target, options, cacheTtl, selections, aliasMap
     return onrejected?.(error);
   }
 }
-async function handleNonCachedQuery(target, selections, aliasMap, onfulfilled, onrejected) {
+async function handleNonCachedQuery(target, options, selections, aliasMap, onfulfilled, onrejected) {
   try {
-    const localCached = await getQueryLocalCacheQuery(target);
+    const localCached = await getQueryLocalCacheQuery(target, options);
     if (localCached) {
       return onfulfilled?.(localCached);
     }
     const rows = await target.execute();
     const transformed = applyFromDriverTransform(rows, selections, aliasMap);
-    await saveQueryLocalCacheQuery(target, transformed);
+    await saveQueryLocalCacheQuery(target, transformed, options);
     return onfulfilled?.(transformed);
   } catch (error) {
     return onrejected?.(error);
@@ -1168,7 +1212,14 @@ function createAliasedSelectBuilder(db, fields, selectFn, useCache, options, cac
                 onrejected
               );
             } else {
-              return handleNonCachedQuery(target, selections, aliasMap, onfulfilled, onrejected);
+              return handleNonCachedQuery(
+                target,
+                options,
+                selections,
+                aliasMap,
+                onfulfilled,
+                onrejected
+              );
             }
           };
         }
@@ -1197,6 +1248,43 @@ const DEFAULT_OPTIONS = {
   cacheEntityExpirationName: "expiration",
   cacheEntityDataName: "data"
 };
+function createRawQueryExecutor(db, options, useGlobalCache = false) {
+  return async function(query, cacheTtl) {
+    let sql2;
+    if (isSQLWrapper(query)) {
+      const sqlWrapper = query;
+      sql2 = sqlWrapper.getSQL().toQuery(
+        db.dialect
+      );
+    } else {
+      sql2 = {
+        sql: query,
+        params: []
+      };
+    }
+    const localCacheResult = await getQueryLocalCacheQuery(sql2, options);
+    if (localCacheResult) {
+      return localCacheResult;
+    }
+    if (useGlobalCache) {
+      const cacheResult = await getFromCache({ toSQL: () => sql2 }, options);
+      if (cacheResult) {
+        return cacheResult;
+      }
+    }
+    const results = await db.execute(query);
+    await saveQueryLocalCacheQuery(sql2, results, options);
+    if (useGlobalCache) {
+      await setCacheResult(
+        { toSQL: () => sql2 },
+        options,
+        results,
+        cacheTtl ?? options.cacheTTL ?? 120
+      );
+    }
+    return results;
+  };
+}
 function patchDbWithSelectAliased(db, options) {
   const newOptions = { ...DEFAULT_OPTIONS, ...options };
   db.selectAliased = function(fields) {
@@ -1208,15 +1296,6 @@ function patchDbWithSelectAliased(db, options) {
       newOptions
     );
   };
-  db.selectAliasedDistinct = function(fields) {
-    return createAliasedSelectBuilder(
-      db,
-      fields,
-      (selections) => db.selectDistinct(selections),
-      false,
-      newOptions
-    );
-  };
   db.selectAliasedCacheable = function(fields, cacheTtl) {
     return createAliasedSelectBuilder(
       db,
@@ -1227,6 +1306,15 @@ function patchDbWithSelectAliased(db, options) {
       cacheTtl
     );
   };
+  db.selectAliasedDistinct = function(fields) {
+    return createAliasedSelectBuilder(
+      db,
+      fields,
+      (selections) => db.selectDistinct(selections),
+      false,
+      newOptions
+    );
+  };
   db.selectAliasedDistinctCacheable = function(fields, cacheTtl) {
     return createAliasedSelectBuilder(
       db,
@@ -1237,6 +1325,18 @@ function patchDbWithSelectAliased(db, options) {
       cacheTtl
     );
   };
+  db.selectFrom = function(table) {
+    return db.selectAliased(getTableColumns(table)).from(table);
+  };
+  db.selectFromCacheable = function(table, cacheTtl) {
+    return db.selectAliasedCacheable(getTableColumns(table), cacheTtl).from(table);
+  };
+  db.selectDistinctFrom = function(table) {
+    return db.selectAliasedDistinct(getTableColumns(table)).from(table);
+  };
+  db.selectDistinctFromCacheable = function(table, cacheTtl) {
+    return db.selectAliasedDistinctCacheable(getTableColumns(table), cacheTtl).from(table);
+  };
   db.insertWithCacheContext = function(table) {
     return insertAndEvictCacheBuilder(db, table, newOptions, false);
   };
@@ -1255,6 +1355,8 @@ function patchDbWithSelectAliased(db, options) {
   db.deleteAndEvictCache = function(table) {
     return deleteAndEvictCacheBuilder(db, table, newOptions, true);
   };
+  db.executeQuery = createRawQueryExecutor(db, newOptions, false);
+  db.executeQueryCacheable = createRawQueryExecutor(db, newOptions, true);
   return db;
 }
 class ForgeSQLAnalyseOperation {
@@ -1722,16 +1824,19 @@ class ForgeSQLORMImpl {
    */
   async executeWithCacheContextAndReturnValue(cacheContext) {
     return await this.executeWithLocalCacheContextAndReturnValue(
-      async () => await cacheApplicationContext.run({ tables: /* @__PURE__ */ new Set() }, async () => {
-        try {
-          return await cacheContext();
-        } finally {
-          await clearTablesCache(
-            Array.from(cacheApplicationContext.getStore()?.tables ?? []),
-            this.options
-          );
+      async () => await cacheApplicationContext.run(
+        cacheApplicationContext.getStore() ?? { tables: /* @__PURE__ */ new Set() },
+        async () => {
+          try {
+            return await cacheContext();
+          } finally {
+            await clearTablesCache(
+              Array.from(cacheApplicationContext.getStore()?.tables ?? []),
+              this.options
+            );
+          }
         }
-      })
+      )
     );
   }
   /**
@@ -1742,9 +1847,12 @@ class ForgeSQLORMImpl {
    * @returns Promise that resolves to the return value of the cacheContext function
    */
   async executeWithLocalCacheContextAndReturnValue(cacheContext) {
-    return await localCacheApplicationContext.run({ cache: {} }, async () => {
-      return await cacheContext();
-    });
+    return await localCacheApplicationContext.run(
+      localCacheApplicationContext.getStore() ?? { cache: {} },
+      async () => {
+        return await cacheContext();
+      }
+    );
   }
   /**
    * Executes operations within a local cache context.
@@ -1973,6 +2081,147 @@ class ForgeSQLORMImpl {
     }
     return this.drizzle.selectAliasedDistinctCacheable(fields, cacheTTL);
   }
+  /**
+   * Creates a select query builder for all columns from a table with field aliasing support.
+   * This is a convenience method that automatically selects all columns from the specified table.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @returns Select query builder with all table columns and field aliasing support
+   * @example
+   * ```typescript
+   * const users = await forgeSQL.selectFrom(userTable).where(eq(userTable.id, 1));
+   * ```
+   */
+  selectFrom(table) {
+    return this.drizzle.selectFrom(table);
+  }
+  /**
+   * Creates a select distinct query builder for all columns from a table with field aliasing support.
+   * This is a convenience method that automatically selects all distinct columns from the specified table.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @returns Select distinct query builder with all table columns and field aliasing support
+   * @example
+   * ```typescript
+   * const uniqueUsers = await forgeSQL.selectDistinctFrom(userTable).where(eq(userTable.status, 'active'));
+   * ```
+   */
+  selectDistinctFrom(table) {
+    return this.drizzle.selectDistinctFrom(table);
+  }
+  /**
+   * Creates a cacheable select query builder for all columns from a table with field aliasing and caching support.
+   * This is a convenience method that automatically selects all columns from the specified table with caching enabled.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @param cacheTTL - Optional cache TTL override (defaults to global cache TTL)
+   * @returns Select query builder with all table columns, field aliasing, and caching support
+   * @example
+   * ```typescript
+   * const users = await forgeSQL.selectCacheableFrom(userTable, 300).where(eq(userTable.id, 1));
+   * ```
+   */
+  selectCacheableFrom(table, cacheTTL) {
+    return this.drizzle.selectFromCacheable(table, cacheTTL);
+  }
+  /**
+   * Creates a cacheable select distinct query builder for all columns from a table with field aliasing and caching support.
+   * This is a convenience method that automatically selects all distinct columns from the specified table with caching enabled.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @param cacheTTL - Optional cache TTL override (defaults to global cache TTL)
+   * @returns Select distinct query builder with all table columns, field aliasing, and caching support
+   * @example
+   * ```typescript
+   * const uniqueUsers = await forgeSQL.selectDistinctCacheableFrom(userTable, 300).where(eq(userTable.status, 'active'));
+   * ```
+   */
+  selectDistinctCacheableFrom(table, cacheTTL) {
+    return this.drizzle.selectDistinctFromCacheable(table, cacheTTL);
+  }
+  /**
+   * Executes a raw SQL query with local cache support.
+   * This method provides local caching for raw SQL queries within the current invocation context.
+   * Results are cached locally and will be returned from cache on subsequent identical queries.
+   *
+   * @param query - The SQL query to execute (SQLWrapper or string)
+   * @returns Promise with query results
+   * @example
+   * ```typescript
+   * // Using SQLWrapper
+   * const result = await forgeSQL.execute(sql`SELECT * FROM users WHERE id = ${userId}`);
+   *
+   * // Using string
+   * const result = await forgeSQL.execute("SELECT * FROM users WHERE status = 'active'");
+   * ```
+   */
+  execute(query) {
+    return this.drizzle.executeQuery(query);
+  }
+  /**
+   * Executes a raw SQL query with both local and global cache support.
+   * This method provides comprehensive caching for raw SQL queries:
+   * - Local cache: Within the current invocation context
+   * - Global cache: Cross-invocation caching using @forge/kvs
+   *
+   * @param query - The SQL query to execute (SQLWrapper or string)
+   * @param cacheTtl - Optional cache TTL override (defaults to global cache TTL)
+   * @returns Promise with query results
+   * @example
+   * ```typescript
+   * // Using SQLWrapper with custom TTL
+   * const result = await forgeSQL.executeCacheable(sql`SELECT * FROM users WHERE id = ${userId}`, 300);
+   *
+   * // Using string with default TTL
+   * const result = await forgeSQL.executeCacheable("SELECT * FROM users WHERE status = 'active'");
+   * ```
+   */
+  executeCacheable(query, cacheTtl) {
+    return this.drizzle.executeQueryCacheable(query, cacheTtl);
+  }
+  /**
+   * Creates a Common Table Expression (CTE) builder for complex queries.
+   * CTEs allow you to define temporary named result sets that exist within the scope of a single query.
+   *
+   * @returns WithBuilder for creating CTEs
+   * @example
+   * ```typescript
+   * const withQuery = forgeSQL.$with('userStats').as(
+   *   forgeSQL.select({ userId: users.id, count: sql<number>`count(*)` })
+   *     .from(users)
+   *     .groupBy(users.id)
+   * );
+   * ```
+   */
+  get $with() {
+    return this.drizzle.$with;
+  }
+  /**
+   * Creates a query builder that uses Common Table Expressions (CTEs).
+   * CTEs allow you to define temporary named result sets that exist within the scope of a single query.
+   *
+   * @param queries - Array of CTE queries created with $with()
+   * @returns Query builder with CTE support
+   * @example
+   * ```typescript
+   * const withQuery = forgeSQL.$with('userStats').as(
+   *   forgeSQL.select({ userId: users.id, count: sql<number>`count(*)` })
+   *     .from(users)
+   *     .groupBy(users.id)
+   * );
+   *
+   * const result = await forgeSQL.with(withQuery)
+   *   .select({ userId: withQuery.userId, count: withQuery.count })
+   *   .from(withQuery);
+   * ```
+   */
+  with(...queries) {
+    return this.drizzle.with(...queries);
+  }
 }
 class ForgeSQLORM {
   ormInstance;
@@ -1985,6 +2234,68 @@ class ForgeSQLORM {
   selectDistinctCacheable(fields, cacheTTL) {
     return this.ormInstance.selectDistinctCacheable(fields, cacheTTL);
   }
+  /**
+   * Creates a select query builder for all columns from a table with field aliasing support.
+   * This is a convenience method that automatically selects all columns from the specified table.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @returns Select query builder with all table columns and field aliasing support
+   * @example
+   * ```typescript
+   * const users = await forgeSQL.selectFrom(userTable).where(eq(userTable.id, 1));
+   * ```
+   */
+  selectFrom(table) {
+    return this.ormInstance.getDrizzleQueryBuilder().selectFrom(table);
+  }
+  /**
+   * Creates a select distinct query builder for all columns from a table with field aliasing support.
+   * This is a convenience method that automatically selects all distinct columns from the specified table.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @returns Select distinct query builder with all table columns and field aliasing support
+   * @example
+   * ```typescript
+   * const uniqueUsers = await forgeSQL.selectDistinctFrom(userTable).where(eq(userTable.status, 'active'));
+   * ```
+   */
+  selectDistinctFrom(table) {
+    return this.ormInstance.getDrizzleQueryBuilder().selectDistinctFrom(table);
+  }
+  /**
+   * Creates a cacheable select query builder for all columns from a table with field aliasing and caching support.
+   * This is a convenience method that automatically selects all columns from the specified table with caching enabled.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @param cacheTTL - Optional cache TTL override (defaults to global cache TTL)
+   * @returns Select query builder with all table columns, field aliasing, and caching support
+   * @example
+   * ```typescript
+   * const users = await forgeSQL.selectCacheableFrom(userTable, 300).where(eq(userTable.id, 1));
+   * ```
+   */
+  selectCacheableFrom(table, cacheTTL) {
+    return this.ormInstance.getDrizzleQueryBuilder().selectFromCacheable(table, cacheTTL);
+  }
+  /**
+   * Creates a cacheable select distinct query builder for all columns from a table with field aliasing and caching support.
+   * This is a convenience method that automatically selects all distinct columns from the specified table with caching enabled.
+   *
+   * @template T - The type of the table
+   * @param table - The table to select from
+   * @param cacheTTL - Optional cache TTL override (defaults to global cache TTL)
+   * @returns Select distinct query builder with all table columns, field aliasing, and caching support
+   * @example
+   * ```typescript
+   * const uniqueUsers = await forgeSQL.selectDistinctCacheableFrom(userTable, 300).where(eq(userTable.status, 'active'));
+   * ```
+   */
+  selectDistinctCacheableFrom(table, cacheTTL) {
+    return this.ormInstance.getDrizzleQueryBuilder().selectDistinctFromCacheable(table, cacheTTL);
+  }
   executeWithCacheContext(cacheContext) {
     return this.ormInstance.executeWithCacheContext(cacheContext);
   }
@@ -2157,6 +2468,85 @@ class ForgeSQLORM {
   getDrizzleQueryBuilder() {
     return this.ormInstance.getDrizzleQueryBuilder();
   }
+  /**
+   * Executes a raw SQL query with local cache support.
+   * This method provides local caching for raw SQL queries within the current invocation context.
+   * Results are cached locally and will be returned from cache on subsequent identical queries.
+   *
+   * @param query - The SQL query to execute (SQLWrapper or string)
+   * @returns Promise with query results
+   * @example
+   * ```typescript
+   * // Using SQLWrapper
+   * const result = await forgeSQL.execute(sql`SELECT * FROM users WHERE id = ${userId}`);
+   *
+   * // Using string
+   * const result = await forgeSQL.execute("SELECT * FROM users WHERE status = 'active'");
+   * ```
+   */
+  execute(query) {
+    return this.ormInstance.getDrizzleQueryBuilder().executeQuery(query);
+  }
+  /**
+   * Executes a raw SQL query with both local and global cache support.
+   * This method provides comprehensive caching for raw SQL queries:
+   * - Local cache: Within the current invocation context
+   * - Global cache: Cross-invocation caching using @forge/kvs
+   *
+   * @param query - The SQL query to execute (SQLWrapper or string)
+   * @param cacheTtl - Optional cache TTL override (defaults to global cache TTL)
+   * @returns Promise with query results
+   * @example
+   * ```typescript
+   * // Using SQLWrapper with custom TTL
+   * const result = await forgeSQL.executeCacheable(sql`SELECT * FROM users WHERE id = ${userId}`, 300);
+   *
+   * // Using string with default TTL
+   * const result = await forgeSQL.executeCacheable("SELECT * FROM users WHERE status = 'active'");
+   * ```
+   */
+  executeCacheable(query, cacheTtl) {
+    return this.ormInstance.getDrizzleQueryBuilder().executeQueryCacheable(query, cacheTtl);
+  }
+  /**
+   * Creates a Common Table Expression (CTE) builder for complex queries.
+   * CTEs allow you to define temporary named result sets that exist within the scope of a single query.
+   *
+   * @returns WithBuilder for creating CTEs
+   * @example
+   * ```typescript
+   * const withQuery = forgeSQL.$with('userStats').as(
+   *   forgeSQL.select({ userId: users.id, count: sql<number>`count(*)` })
+   *     .from(users)
+   *     .groupBy(users.id)
+   * );
+   * ```
+   */
+  get $with() {
+    return this.ormInstance.getDrizzleQueryBuilder().$with;
+  }
+  /**
+   * Creates a query builder that uses Common Table Expressions (CTEs).
+   * CTEs allow you to define temporary named result sets that exist within the scope of a single query.
+   *
+   * @param queries - Array of CTE queries created with $with()
+   * @returns Query builder with CTE support
+   * @example
+   * ```typescript
+   * const withQuery = forgeSQL.$with('userStats').as(
+   *   forgeSQL.select({ userId: users.id, count: sql<number>`count(*)` })
+   *     .from(users)
+   *     .groupBy(users.id)
+   * );
+   *
+   * const result = await forgeSQL.with(withQuery)
+   *   .select({ userId: withQuery.userId, count: withQuery.count })
+   *   .from(withQuery);
+   * ```
+   */
+  with(...queries) {
+    return this.ormInstance.getDrizzleQueryBuilder().with(...queries);
+  }
 }
 const forgeDateTimeString = customType({
   dataType() {