forge-sql-orm 2.1.0 → 2.1.1

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);
@@ -1024,11 +1046,34 @@ 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;
@@ -1197,6 +1242,41 @@ 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);
+    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);
+    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 +1288,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 +1298,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 +1317,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 +1347,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,7 +1816,7 @@ class ForgeSQLORMImpl {
    */
   async executeWithCacheContextAndReturnValue(cacheContext) {
     return await this.executeWithLocalCacheContextAndReturnValue(
-      async () => await cacheApplicationContext.run({ tables: /* @__PURE__ */ new Set() }, async () => {
+      async () => await cacheApplicationContext.run(cacheApplicationContext.getStore() ?? { tables: /* @__PURE__ */ new Set() }, async () => {
         try {
           return await cacheContext();
         } finally {
@@ -1737,19 +1831,19 @@ class ForgeSQLORMImpl {
   /**
    * Executes operations within a local cache context and returns a value.
    * This provides in-memory caching for select queries within a single request scope.
-   *
+   * 
    * @param cacheContext - Function containing operations that will benefit from local caching
    * @returns Promise that resolves to the return value of the cacheContext function
    */
   async executeWithLocalCacheContextAndReturnValue(cacheContext) {
-    return await localCacheApplicationContext.run({ cache: {} }, async () => {
+    return await localCacheApplicationContext.run(localCacheApplicationContext.getStore() ?? { cache: {} }, async () => {
       return await cacheContext();
     });
   }
   /**
    * Executes operations within a local cache context.
    * This provides in-memory caching for select queries within a single request scope.
-   *
+   * 
    * @param cacheContext - Function containing operations that will benefit from local caching
    * @returns Promise that resolves when all operations are complete
    */
@@ -1973,6 +2067,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 +2220,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);
   }
@@ -1994,7 +2291,7 @@ class ForgeSQLORM {
   /**
    * Executes operations within a local cache context.
    * This provides in-memory caching for select queries within a single request scope.
-   *
+   * 
    * @param cacheContext - Function containing operations that will benefit from local caching
    * @returns Promise that resolves when all operations are complete
    */
@@ -2004,7 +2301,7 @@ class ForgeSQLORM {
   /**
    * Executes operations within a local cache context and returns a value.
    * This provides in-memory caching for select queries within a single request scope.
-   *
+   * 
    * @param cacheContext - Function containing operations that will benefit from local caching
    * @returns Promise that resolves to the return value of the cacheContext function
    */
@@ -2157,6 +2454,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() {